記事

プログラムのコメントに『何をしているコードか』を書いても無意味なので、代わりに『なぜそのようなコードになったのか』を書くようにしよう

 タイトルで全部言い切ってしまいましたので、後は冗長に書いてブログエントリーに仕立てます。


 職業上、プログラムを毎日観ていていますが、一番多いコメントが『何をしているコードか』というものです。「ここでトランザクションを開始する」「もしEOFだったらファイルを閉じる」「セミコロンで分割して最初の文字を取得する」などなど……

 それって、要ります??

 構造や内容については、その言語が読める人なら誰でも解るものです。そもそもコードを読んでる時点で当たり前の部分はクリアしている人のはずなのだから、上記のような『何をしているコードか』は書くまでもないこと*1で、不要なコメントです。

 不要なコメントは削除しましょう。

 コメントはコンパイルするときに無視されるものです。ソースの内容とコメントが食い違っていてもコンパイルエラーは出ません。コメントは増えれば増えるほど、ソースの内容と異なるコメントをはらむ危険性が増します。ソースの内容と異なるコメントは、読み手に混乱を与えます。よって、不要なコメントは入れるべきではありません。『何をしているコードか』というコメントは削除対象です。

 ではどういうコメントを残すのか?

 それを考える前に、もうちょっとだけ前提を詰めておきたいです。

 そもそも、コメントを残す目的ってなんでしょう?

 それは「保守者に情報を伝えるため」です。コメントの有無によってプログラムの動作は変わりませんし、コンパイラはコメントを無視します。コンパイラ以外でプログラムに触れるのは保守者ですから、コメントは保守者のためにあると言えます。では何の情報を伝えればいいのでしょうか? それは『なぜ』です。

 『なぜそのようなコードになったのか』を残すべきです。

 保守者が知りたいのは『なぜそのようなコードになったのか』です。既存のコードに手を入れて変更するにしても、セオリー通りではないコードは「なぜそうなっているのか」が解らないと手を入れられません。一見すると冗長でバグがありそうなコードだけれど、もしかしたら複雑な理由があるのかも? そう考えたら迂闊には手を入れられません。『何をしているコードか』は、時間を掛ければ読み解くことができます。しかし「なぜそうやったのか」は書いたプログラマーの頭の中にしかありませんから、コードから読み取ることはできません。だからこそコメントで補完する必要があるのです。更に、保守者への注意喚起まで残っていると素敵。


 プログラマーに話を聴くと、コメントを「なんとなく」で入れている人が結構多いです。コメントはどう書こうがプログラムの内容には影響しないので、あまり重視されていないのでしょう。とはいえ、コメントも成果の一つ。更に、保守者への大事な情報源です。ちょっとばかり気を遣って「なんとなく」で入れるのは止めにしませんか。



*1:説明を書かないと何をやっているのか解らないコードは、それ自体がバグの元なので書きなおすべき

あわせて読みたい

「プログラミング」の記事一覧へ

トピックス

  1. 一覧を見る

ランキング

  1. 1

    BLOGOSサービス終了のお知らせ

    BLOGOS編集部

    03月31日 16:00

  2. 2

    なぜ日本からは韓国の姿が理解しにくいのか 識者が語る日韓関係の行方

    島村優

    03月31日 15:41

  3. 3

    「いまの正義」だけが語られるネット社会とウェブ言論の未来

    御田寺圭

    03月31日 10:09

  4. 4

    カーオーディオの文化史 〜ドライブミュージックを支えた、技術の結晶たち〜

    速水健朗

    03月30日 16:30

  5. 5

    BLOGOS執筆を通じて垣間見たリーマンショック後10年の企業経営

    大関暁夫

    03月31日 08:27

ログイン

ログインするアカウントをお選びください。
以下のいずれかのアカウントでBLOGOSにログインすることができます。

コメントを書き込むには FacebookID、TwitterID のいずれかで認証を行う必要があります。

※livedoorIDでログインした場合、ご利用できるのはフォロー機能、マイページ機能、支持するボタンのみとなります。