前に作ったEsCaveの方もP5Docletを使った出力にしておいたけど、そのために後付けでコメントを振ったので疲れた。普段privateなフィールドやメソッドにコメントなんかあんまりつけないし。昔ベーマガへの投稿プログラムに
99 REM *** がめんせってい ***
とかをプログラムができあがった後につけてたことを思い出したよ。
そもそも最近の風潮として、詳細なコメントを振るよりもリファクタリングでソース自体の可読性を上げなさいってのが主流なので、一つ一つのメンバにコメントを振るってのはあんまり実用的ではないなあ。ソースに加えてどういった出力があるとコードの理解の役に立つんだろう。
久しぶりに昔のベーマガみたら、プログラムマップとかいうのがあって
9〜15 初期設定 33〜250 メイン 400〜530 ヒトの攻撃
とか、行番号でブロックわけしたプログラムの機能が書いてあった。今ならこのレベルの抽象化はクラスとメソッドでいくらでもできるので、こういった説明書きはほぼ不要といえる。
プログラミングになじみのない人向けにプログラムを説明する場合、近代的な言語で書かれた小規模なソースコードそれ自体以外に、ドキュメントで補わなければいけない情報はあるのだろうか。それとも適度にコメントの振られたソースがあればそれで十分なのかね。
