ゴールデンウィークなので折角だから借りてきた。

──というのは嘘。実際の所は、図書館のカードを更新しに行ったついでに気の迷いで借りてしまっただけ。

以前も借りたことがあるのだが、『プログラム書法 第2版』は良い本ではあるけどちょっと古すぎる。サンプルコードがFortran*1やPL/I*2である時点でこの本の良さが大幅に削がれている。21世紀のプログラマには色々と厳しい。

まあ今や後継たる『プログラミング作法』がある訳で、普通はそちらを推奨するのだが。

ただ何というか、コメントの書き方に関する記述は『プログラム書法』の方が分かりやすいと思うのだ。分かりやすいというか、『プログラミング作法』よりも基本的な部分に焦点が当てられているというか。単なる気分の問題かもしれないけど。

という訳で、『プログラム書法』に出てくる規則集を元に、コメントの書き方についてまとめてみた。不足する点は他の文献から適度に補うことにする。ちなみに「注釈＝コメント」だ。

「プログラムに書いてあることを注釈でおうむがえしにするのはよそう。つけ甲斐のある注釈をつけよう」 初心者に「コメントを付けましょう」とだけ注意すると発生する、NGパターン。 ソースコードの内容をそのまま自然言語に置き換えたようなコメントは無価値だ。というかソースを読めば済む話なので。そのようなコメントを付ける前に、ソースを適切にインデントするとか、分かりやすい名前を採用するとか、やるべき事が沢山ある。 なによりこの手のコメントは、前項に書いた「プログラムの中身を二重に表現している」にもろに該当している。コード修正の為にコメントもメンテしなくてはならない、厄介な代物だ。無価値なのにコストばかりかかるのだから、当然ながら避けるべきろう。それだけでコメントのメンテナンスのコストが減り、楽になる。 まずはソースコード自体を解説文書となるような読みやすいものにするべきだ。適切なインデント、シンプルな制御構造、分かりやすい名前（変数名、関数名、その他）……これらを採用するだけでも随分見通しのよいソースコードになる。見通しがよければソースの誤りも見つけやすくなるし、ソース本体が読みやすいのだから内容をおうむがえしするコメントなどまったくもって無価値だ。ソースの読み辛さをコメントでフォローしようなど本末転倒だ。 その上で、どのようなコメントを書くべきだろうか？ 「つけ甲斐のある注釈」とはどのようなものだろうか？ 基本方針として、コメントはソースコード自体からは簡単には分からないような新しい情報を提供するものでなくてはならない。このような内容のコメントはソースコード本体からすると量は少なくなる傾向にあると思う。まさにソースコードが主役で、コメントは添え物程度な訳だ。 私の個人的見解*5としては、HowよりWhat、WhatよりWhyを書くべきだ。 How どのような方法で？ 要するにソースの内容をおうむがえししているようなコメント What 何を？ 幾つかの処理をまとめて要約したコメント。基本的にドメインに着目した視点で書く。 Why なぜ？ なぜこんな処理をしているのか、なぜこの順番なのか、etc. Whatはソースコードから分かりにくい or 読み取るのに時間が掛かる場合がある。Whyは大抵ソースコードから読み取るのことが難しい。だからこそ、後でソースコードを読む他人の理解を助けるためにも、Whyは積極的に、Whatは熟慮した上で、コメントとして書き残しておくべきだ。 あとコメントは明快に書くこと。理解を助けるためのコメントがかえって混乱を招いたり、疑問を増やしてしまってはダメだ。 まあしかし、これだけでは実際にどんなコメントを書いたらよいか分かりにくい。とくに経験が浅い人はチンプンカンプンだろう。