━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■第3回 コメントに愛を
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
今日はプログラミングの話題です。
私は、趣味でオープンソースのプログラムを作っているのですが、一番注意
していることは、コメントの書き方です。
もちろん、プログラムの品質も重要なのですが、オープンソースの場合は、
利用者が不具合を修正できるという特徴があるので、品質以上に気を使わな
いといけません。
誰が読んでも理解できる。
そんなレベルのコメントを書くのが理想です。
●ですますコメント
私が推奨しているのが、「ですますコメント」です。
その名のとおり、語尾がですます調になります。
例えば、
// 社員登録
社員マスタ.Save();
こんなコードがあったとします。
これを、「ですますコメント」に変えると、以下のようになります。
// 入力データを社員テーブルに登録します。
社員マスタ.Save();
なんとなくですが、温かみがあるような気がしませんか？
最初の例では、単語だけのコメントだったのに対し、「ですますコメント」
では、語りかけるような文章で説明しています。
人との会話も同様です。
「これってどういう意味ですか？」と聞かれ、「社員登録」とだけボソっと
言われたら、あまりいい気分ではないですよね。
自分以外の人の書いたコードを読むのは、多くの場合、楽ではありませんか
ら、せめてコメントだけでも気分良く読んでもらいたいものです。
ソースコードの半分は優しさで作られています。
●ドキュメントの自動生成
コメントの優しさついでに、ドキュメントの自動生成も考えてみたいと思い
ます。
最近の開発ツールには、コメントからドキュメントを生成できるものが増え
てきたように思います。
Javaには、Javadocがあり、.NETにも、SandCastleというツールがあります。
（SandCastleはまだベータ版ですが、十分に使えます）
これらのツールは、ソースコード上に決められたフォーマットでコメントを
記述しておくことにより、HTML形式やHelp形式のファイルを生成することが
できます。
ソースコードから生成されたドキュメントなので、コードと整合性が取れて
いるため、クラスの関係を知りたいときや、目的のクラスを探すときなどに
大変便利です。
それだけでなく、このドキュメントが納品物として認められるケースも多い
ため、ドキュメント作成に費やす時間を削減することも可能です。
私の場合、詳細設計フェーズでクラスを作成し、コメントを埋めてドキュメ
ントを生成しています。（ビジネスロジックは書いていません）
詳細設計書の一部として納品できるので、コストが削減できます。
開発フェーズになると、既にクラス、メソッド類が定義されており、使い方
がコメントとして書かれているため、プログラマはスムーズに作業すること
ができるだけでなく、設計通りの実装に導くことができるのです。
※ クラス設計がきちんとできていることが前提となります。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━