記事

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

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


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

 それって、要ります??

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

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

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

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

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

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

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

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

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


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



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

あわせて読みたい

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

トピックス

ランキング

  1. 1

    猫の目が…奇跡の失敗写真が話題

    BLOGOS しらべる部

  2. 2

    立民党はなぜ全く期待できないか

    宇佐美典也

  3. 3

    収監された周庭さん 12人部屋に

    BLOGOS しらべる部

  4. 4

    社民党を食いつぶした福島瑞穂氏

    文春オンライン

  5. 5

    安倍氏に弁護士「虚構だった?」

    郷原信郎

  6. 6

    投資家がマイホームのリスク指摘

    内藤忍

  7. 7

    GoTo見直しで焦る日本の敗戦模様

    文春オンライン

  8. 8

    人気のセ・実力のパに「違和感」

    中川 淳一郎

  9. 9

    タトゥー女子急増?「映え目的」

    ABEMA TIMES

  10. 10

    菅氏はカジノより介護を優先せよ

    毒蝮三太夫

ランキング一覧

ログイン

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

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

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