記事

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

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


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

 それって、要ります??

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

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

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

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

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

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

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

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

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


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



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

あわせて読みたい

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

トピックス

ランキング

  1. 1

    コロナ巡り医師がTBSで政府批判

    水島宏明

  2. 2

    「映像研」落語好きが唸るアニメ

    松田健次

  3. 3

    新型インフル抑えた「過剰反応」

    井戸まさえ

  4. 4

    たらい回し? 肺炎報道に医師苦言

    中村ゆきつぐ

  5. 5

    籠池氏への不当な国策判決を批判

    郷原信郎

  6. 6

    口頭決裁? 権力の私物化が露呈か

    音喜多 駿(参議院議員 / 東京都選挙区)

  7. 7

    厚労省の審議官が船内で問題行動

    文春オンライン

  8. 8

    口頭決裁を認めた森法相に苦言

    早川忠孝

  9. 9

    なぜ企業に資金が滞留するのか

    ヒロ

  10. 10

    肺炎めぐる煽り報道は自制せよ

    青山まさゆき

ランキング一覧

ログイン

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

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

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