Doxygen
Doxygen、ご存知ですか?
ソースコードのドキュメント化ツールで、ソースコード中にコメントの形でテキストを埋め込んでおくと、それを解析してクラスや関数の使用説明書をイイ感じの html なり pdf なりにまとめてくれるというものです。
これが…
こうなる!!
コメントは....重要なんですよ。
あれは他人のために書くものではなく、未来の自分のために書くものです。
断言します。
ヴィータ大脱出や滅びの国の王女のソースを今見ても結構(^ω^;)??ってなることが多いですから。これまでどんなにコメントに助けられたことか。
自分が書いたモノでさえそうなのに、まして他人のプログラムを解析して手を加える事のできる人は本当に尊敬します。
ところでコメントは濃度が薄すぎても濃すぎてもダメですよね。
コメントは本当に重要なところだけに書くのが良い、という意見を見ることもありますが、個人的には少しクドイぐらいが丁度良いのではないかなと思います。
でもさすがに
i++; // インクリメント
なんてコメントは書きませんが。
話がズレましたが、Doxygen が関係するのは関数内のコメントではなく、関数やクラスの仕様に関するコメントです。これは〇〇する関数で引数は〇〇、戻り値は〇〇で……みたいな。
これだけでもちゃんと書いてあると、あとあと凄く楽なんですよ(実体験)。
ただ、ソースファイルの数が多くなってくると、どのファイルにどのクラスや関数が入っているのかを把握するのが面倒になってきますし、いちいちファイルを開いてコメントを確認するのも大変になってきます。
そこで Doxygen ですよ。
これで html ドキュメントを作成しておけば、リンクをクリックするだけで説明を読むことができます。
ありがとう Doxygen!!
ちなみに Doxygen が出力した HTML ですが、例えば以下のサイトは両方ともソースコードのコメントから Doxygen が自動生成したモノです。
Cocos2d-x
https://docs.cocos2d-x.org/api-ref/cplusplus/v3x/
Irrlicht
http://irrlicht.sourceforge.net/docu/index.html
SFML
https://www.sfml-dev.org/documentation/2.5.1/
SFML なんかは洗練されていますね。
自動生成と言ってもカスタマイズやスタイルシートの利用などが可能なので、適切に設定してやれば格好の良いものが出来上がります。