出直し!! ドミノ塾: コメントの書き方

ほかの開発者が作成したプログラムがわかりにくいと感じませんか？

その理由は、仕様やインターフェースが不明瞭であったり、プログラムの構造が自分自身の思考とは違っていたり、コーディングの癖が生理的に合わなかったりさまざまです。

ただ、このような状況であっても、コード内のコメントが適切に記述されていれば状況は改善されています。そこで、今回はコード内のコメントの書き方について整理したいと思います。

コメントの種類

プログラム内のコメントは次の 4 つに大別できます。

変数コメント

変数コメントは、変数宣言でその変数の用途を記述するもので、変数宣言の右側に続けて記述すると場所を取らずわかりやすくなります。

まれにすべての変数に対してコメントされているプログラムを見ることがありますが、必要最小限にしておかないとかえって見づらくなります。

ループ変数など汎用的な変数、NotesSession や NotesUIWorkSpace など中身が固定的なものは不要です。

例えば、ステータスの変数では、とりうる値やその値の意味、単語を省略した変数名では誤解を招かないよう注記するなど、重要な変数だけにとどめましょう。

ブロックコメント

プログラム内に記述するコメントです。

ビューから次の文書を取得する GetNextDocument メソッドに対して『次の文書を取得』などとコメントしているプログラムを見ることがあります。このようなコードを見ればすぐわかるコメントは不要です。

ブロックコメントは、一連の機能や複雑な部分に対して説明するコメントすると有用です。例えば、あるループ処理があったとして、ループ内の機能概要やループの継続条件/終了条件を記述すると効果的です。

関数ヘッダコメント

関数の先頭に記述するコメントで、機能や使い方を記述します。例えば次のような項目です。

これらが記述されていると、安心して関数を利用できます。すべての関数について記述することが望ましいですが、少なくともパブリックな関数には必ず記述しましょう。

ライブラリヘッダコメント

スクリプトライブラリの機能や使い方を記述するコメントで、スクリプトライブラリの先頭である Options セクションの先頭に記述します。

記述する内容は次のような項目です。

不要なコメントの削除

プログラムの修正履歴や修正前のコードをコメントして一時保管することがよくあります。修正を繰り返したプログラムだとコメントだらけになり、現在のコードのためのコメントがどれか判別できなくなります。

不要となったコードの残骸、修正前のコードのコメント、必要以上の更新履歴は削除するようにしましょう。

まとめ

プログラム内に適切にコメントがあると、プログラムの理解が早くなります。

後任の開発者が最初によりどころとするのはコメントです。プログラムの動作に関係なくても、ビジネス上は重要な役割を持つといってもいいでしょう。手を抜くことなく、しっかり記述しましょう。また、修正時にはコメントもメンテナンスするとよいかと思います。

出直し!! ドミノ塾