プログラムのコメントは愚痴を書こう

他人が作ったプログラムを見ていて役に立った経験がほぼありません。
「見りゃ分かるよ」という類のコメントがほとんどですね。

世界一役に立たないコメント例

    'ループ変数に初期値0を入れる。
    i = 0
    While (true)
    :

見りゃ分かる

たまに、プログラムの和訳のようなコメントもありますが、プログラムを読んだ方が間違わないし。
コメント教育って必要なんじゃね？って思います。

設計書を充実させればよいじゃんというご意見もあると思いますが、設計書はプログラムと乖離しやすいと思います。特にバグなどの緊急対応時に、まず設計書を直してレビューがあるまでプログラミングは待つといった悠長なプロジェクトを経験したことがないですね。

#役に立つコメントって、
コメントを読むシチュエーションとは、こんなケースだと思う。

• 不具合が発生して緊急対応が必要な時。もしくは、仕様変更依頼がきた。

• 開発当時のプログラマーはいない。

• 詳細設計書から、どのようなデータを取得して、どう処理すべきかは把握している。でも、実際のプログラムは想像を超えていた。

• 不思議なプログラミングに対して、「技術的な制約があるのか」と不安になり調査時間がかかる。

こんなコメントが望ましい

    '----------------------------------
    'このプログラムはガチャガチャしてます。
    'もっとシンプルに作成できると思うが、
    '途中で仕様変更が襲来したから突貫で直した。
    '
    'プログラムの流れはコレ
    '　１．テーブル　⇒　変数に格納
    '　２．変数から　⇒　一時テーブルに格納
    '　３．一時テーブル　⇒　もう一度、変数に格納
    '　４．CSV出力します。
    '
    'Update  20xx/12/24 23:40 メリークリスマス
    '----------------------------------

詳細設計書には載っていない部分の説明が、書いてあって理解が早くなります。

そして、「あー。いろいろあって、プログラムがガチャガチャしてしまったのね。」と技術的な制約への不安が払しょくされますし、更新日時刻に残る細やかな主張から優しい気持ちでプログラムの解読ができます。

#なぜ愚痴か

###まず、プログラマーは作文能力が低いです。

プログラマーは理系が多いので、設計書のような形式ばった文章だと情報が洩れる人が多いです。つまり、文章を書くのが苦手な彼らにどうしたら情報を漏らさずに書かせるかが重要となります。
少なくともしゃべり言葉で書いてもらった方だ断然伝わる情報になります。

「しゃべり言葉で書いて」と依頼していたのですがそれでもまだ慣れない形式ばった文章を書くので、さらに踏み込んだ結果「愚痴を書け」に落ち着きました。

結論。プログラムのコメントは、愚痴を書こう