Chocolateの楽園を目指して

-楽園を目指す過程での試行錯誤を記していきます-

コード中のコメントは迷える羊たちの道標

今回は、プログラムに記述するコメントについてまとめたいと思います。

コメントの記述ルールに関しても、人それぞれ思うところがあり、

様々なルールがまとめられていますよね~。

私は以下のルールでコメントを記述しています。

  • doxygenルールを使用する。(リファレンス作成のため)
  • コードの分かり切ったコメントは書かない
  • メンバ変数や関数の引数のコメントには、単位、取りうる値の範囲を記述する
  • 処理の流れの概要は記述する
  • クラスのヘッダコメントには、サンプルコードを書き、使い方を具体的に示す
  • 過去のコードをコメント化して履歴としない

大まかには、こんなところですね~。

 

コードの分かり切ったコメントは書かない

これは、下記のような例です。

void update( elapsed_time )

{

    all_time += elapsed_time;   // 総経過時間に今回の経過時間を足す

}

 

数行レベルのコードにおいて、明確に内容が読み取れることにはコメント不要とします。

 

処理の流れの概要は記述する

これは、プログラムができる人が、

コードを読めば一目瞭然なので(そうなるようにコードを記述するべき)として、

省略を奨めることも多いですが、私は記述を推奨します。

チームで仕事をする場合、他人のコードを読む機会も増えますが、

そういうときに流し目でざーと確認するとき、こういったコメントは有効です。

また、私が勧めたい1番の理由は、検索するときのタグ付けの意味合いもあります。

チームで大規模な開発を行う際、他人のとある仕様の実装を確認したいときなど、

流れにコメントが入っていると、すぐに検索できる場合が多いです。

void initialize()

{

   // XXXデータの読み込み

  data = loadRequestData( "XXX01.bin" );

  // XXXデータの初期化

  data.setup();

  // XXXの更新、描画登録

  entryUpdate( data );

  entryRender( data );

}

 

 

 過去のコードをコメント化して履歴としない

これは、今時バージョン管理ソフトを使わないプロジェクトなんて無いと思いますが、

こういったことをする方は多いです。

習慣となっているのかもですが、まったく無駄な領域となりますので削除します。

まれに残したいときもありますが、そういったときは、残している理由をコメントして書きます。

 

といった感じですね。

当たり前のことをただ述べているだけですが。。。

チームとして仕事を行う際、全員の効率が上がるルールとして、お願いしています。

コメント不要論は、私のような普通プログラマーには酷なので、

このようなルールでコメントを書いてもらえると嬉しいです!

 

レガシーコード改善ガイド (Object Oriented SELECTION)

レガシーコード改善ガイド (Object Oriented SELECTION)

 

 

 

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)