コードリーディングが必要となる場面は、バグ修正や新規機能追加、ライブラリやフレームワークの選定など多種多様ですが、コードリーディングの成果とはどういったものでしょうか？また、コードリーディングの成果を何らかの形で資料として残すことは可能でしょうか？

コードリーディングを行って理解した内容を人に伝えることは案外難しいものですが、コードリーディングの成果を資料の形で残すことができるのならば、共有することも容易になるはずです。

そこで本記事では、AWS Cloud9 IDEのもとになっているAce (Ajax.org Cloud9 Editor)というコードエディタのコードリーディングを例にとって、コードリーディングの成果を資料として残す試みについて紹介します。

Aceの基本機能（編集、表示、シンタックスハイライト）について

Aceは以下のようなER図で表される6つの主要なクラスで構成されています。[1]

コードリーディングを行ってテキスト編集機能を実現しているクラスを調べていくと、Editor, EditSession, Documentの3つのクラスが編集機能の中心になっており、

Editor -> EditSession -> Document

のような命令のフローでDocumentオブジェクトに格納された文字列データを編集していることがわかりました。またEditor, VirtualRenderer, Layerの3つのクラスは、Layerオブジェクトに格納されたDOMを

Editor -> VirtualRenderer -> Layer

という命令のフローで操作しており、これによって（入力されたテキストの）表示機能を実現していました。さらにEditor, EditSession, TextMode（または言語ごとのModeクラス）の3つのクラスによってシンタックスハイライト機能を実現していました。シンタックスハイライト機能に使われるトークンやそれらを生成するための正規表現はTextModeクラス（または言語ごとのModeクラス）に格納されていました。

ここまでがコードリーディングによって理解できた内容であり、これが成果です。ある程度簡潔にまとめられたと思いますが、こういった文章による説明をもっとわかりやすい資料に落とし込みたいです。これらの成果を使ってどういった資料を作ることができるでしょうか？

ER図に追記する

テキスト編集機能、表示機能、シンタックスハイライト機能というコードエディタにおける基本機能がそれぞれ3つのクラスを中心として実現されていることがわかり、これら3つのクラスの命令のフローと扱うデータも明らかになったので、これらをさきほど紹介したER図に書き込んでみます。

もとからあった矢印を色分けしデータを格納しているクラスの横にデータ名を記載しただけですが、これだけの作業でもコードリーディングの成果がかなりわかりやすくなったと思います。このように視覚的に表現すると一目瞭然なので人に伝えることも苦になりません。この資料化のポイントは、基本機能と実装との関係を明らかにした ことにあります。

機能仕様と技術仕様の対応表を作る

今回はAceの公式サイトにER図が掲載されていたので追記するだけで済みましたが、そんなに都合のいい状況ばかりではありません。もっとかんたんな方法でさっと作ることができるものも検討してみました。

さきほどは基本機能と実装の関係を明らかにすることによってコードリーディングの成果をわかりやすく表現できました。この考え方を利用します。

基本機能と実装について、"Joel on Software"の機能仕様に関する記事[2]のなかに参考になる説明がありました。

A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.

A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.

機能仕様とは、ユーザー視点で製品がどう動くのかを記述したものであり、技術仕様とはプログラムの内部実装を記述したものであると説明しています。

この説明を参考にして、コードリーディングで理解できた内容を以下のように表にまとめてみました。

機能仕様 (ユーザー視点)	技術仕様 (内部実装)
Edit	`Editor` -> `EditSession` -> `Document`
Display	`Editor` -> `VirtualRenderer` -> `Layer`
Syntax highlighting	`Editor` -> `EditSession` -> `TextMode`

シンプルな表ではありますが、 機能仕様と技術仕様の対応関係 を理解するには十分な資料となりました。ER図のようなものがなくても、このくらい簡素な表であれば手軽に作成できるでしょう。

まとめ

コードリーディングによって得られた成果を資料として残す方法について検討し、ER図に視覚的な形で付け加える方法と機能仕様と技術仕様の対応関係を表にまとめる方法を紹介しました。

コードリーディングは内部実装（＝技術仕様）を読み解く作業となるため、そこで得られた情報（＝コードリーディングの成果）をユーザー視点でもわかる情報（＝機能仕様）と結びつけて対応関係を明らかにすることでわかりやすく、伝えやすい資料として残すことができそうです。

コードリーディングの成果を人に伝えるためのかんたんで便利な方法はまだ他にもあるかもしれません。今後もさらなる改善を求めていこうと思っています。もし何か知見をお持ちの方がいらっしゃいましたら、ぜひ教えてください。

参考

[1] https://ajaxorg.github.io/ace-api-docs/index.html
[2] https://www.joelonsoftware.com/2000/10/03/painless-functional-specifications-part-2-whats-a-spec/