比較的規模の大きいソースコードを見る際、何らかの目的を持った上でソースコードを読み始める。
目的の粒度は大なれ小なれ「コードのどこに着目するか」という疑問は必ず生じる。
パズルも完成形の絵柄を知らずに組み立てるのと 予め出来上がった後の形を知った上で組み立てるのとで 完成の時間が変わってくるように、ソースコードもその全体の形ができるだけ見えた方が良い。
とはいえ、数千行～数万行のコードを相手に 自分の手で一つ一つのクラスの役割や関連性を整理するのも得策ではないので、ここは一つ先人の知恵を活用した方が良さそう。
ということで、今回はソースコードリーディングのお供として活躍してくれるドキュメント自動生成ツール「Doxygen」と、構造体やクラス間の関係を図で出力してくれる「Graphviz」を紹介。
プログラミングの勉強中に何かの本のサンプルコードを読み解く上でも十二分に力を発揮してくれるので強くオススメする。
Doxygen
C、C++、C#、Java、PHP、Python、Objective-Cなど様々な言語に対応。
Rubyは将来的には公式で対応されるっぽい話がStackOverFlowの誰かの回答でチラッと出てたけど、現在の所対応していない模様( Rubyの場合のドキュメント生成ツールとしては RDoc や Yard 等が存在する )。
以下は 書籍 『プログラミング言語を作る』で出てくるプログラミング言語( ベースはC言語 )のドキュメントを自動生成した例。Class Listとは書いてあるが、C言語の場合 構造体がリストに反映されている。
各リンクをクリックすると以下のような形で その構造体が持つ属性を見ることができる。
とはいえ、これだけだと それぞれの構造体の関係性が見えづらいので Graphvizを導入することにする。
Graphviz
「DOT言語」というDSLで書かれたグラフの表現を画像にしてくれるツールみたいです。Doxygenに限定されたライブラリというわけでは無いようだけど、DoxygenがGraphvizによる出力を設定ファイルで指定できるようにしてくれている等、Doxygenとは親和性が高い。
Graphvizと連携させると ドキュメントの他にこんな感じでクラス・構造体間の関係性が見られるようになるみたい。
全体の構造が圧倒的に見えやすくなるのでこれは便利。
インストールから導入まで
Macの場合
Homebrew を使用すると圧倒的に楽。
brew install doxygen graphviz
これだけ。
doxygen -g
で DoxyFile という設定ファイルがカレントディレクトリに生成されるので、設定ファイルを編集して 再帰的にディレクトリ探索するようにしたり Graphvizと連携するようにしたりしてあげる。
詳細な設定に関しては以下の記事がとても分かりやすくまとめられていて参考になった。
ソースコードを読むのに Doxygen + Graphviz が便利な件
編集したDoxyFileは ドキュメントを生成したいプロジェクトのディレクトリに突っ込んで、そのディレクトリ上で以下のコマンドを実行。
doxygen
すると html というディレクトリができるので、そのディレクトリ中の「index.html」にアクセス。
ただ、元々「html」というディレクトリがある場合 ディレクトリ名が 競合して失敗する可能性があるので、そういう場合は予め「html」というディレクトリを「html_temp」とかに変えておいて doxygen で html ディレクトリを生成して、生成したディレクトリの名前を変えてから html_tempを元のディレクトリ名に戻すか、もしくは doxygenを実行するディレクトリを一階層下げるとかそういう対応が必要になりそう。
Windowsの場合
DoxyWizard というのも同時にインストールされる筈なのでそれを立ち上げる。
そこで、以下の5つを設定。
1. Wizard > Project > Project name で プロジェクトの名前を指定。
2. Wizard > Output > Select the output format(s) to generate にて 「LaTex」のチェックを外す。
3. Wizard > Diagrams > Diagrams to generate を「Use dot tool from the Graphviz package」にチェックを入れる。
4. Expert > Dot > HAVE_DOT に チェックを入れる。
5. 4の後、 DOT_PATH で Graphviz のバイナリファイルが入っているフォルダを記述する。
(例: C:\Program Files (x86)\Graphviz2.36\bin )
これら5つを設定した所で、
File > Save as … で DoxyFile を ドキュメントを生成したいディレクトリに保存。
あとの手順はMacと同様。
※ なお、MacにしてもWindowsにしても、DoxyFileは使い回しができるので どこかに保持しておくことを強くオススメする。
というわけで今回は Doxygen & Graphviz を紹介した。ハッピーコードリーディングライフを(´・ω・`)
Written by Nisei Kimura ( 木村 仁星 )
