ソースにコメントを書くのはなぜか

優れた設計、優れたプログラムであればあるほど、コメントは不要である、というのが真理の一つだと思う。もっとも、「優れた」の中にも「複雑なハックを駆使してとにかく高速化」とかそのたぐいの物はあって、そういうものにコメントがないのはパズルや入試問題を解かされているような不毛があるので仕事という面であれば避けたいものではある。

であるならば、コメントを書くのはどういう場合なのか。

至極簡単な理由は、優れたプログラマーなどそんなにいない、というまた別の真理によるものだ。コードにコメントを書かないことを目指すべきであることと、実際にコメントが不要なコードが書けることはイコールではない。業務プログラマーの世界であれば尚更である。そこで目指されているのは完璧なクオリティーのコードを書くことではなく、QCDが計画の範囲内に収まることであるから…

ただ、不要なコメントもたくさんある。特に処理そのものの説明をコメントにしているのは流石にどうかと思う。書くべきなのはその処理の仕方を採択した理由であったり、処理そのものの話であってもコードや仕様書からさくっと読み取れない仕掛けの部分（これは大抵の場合設計がクソなんであるが、プログラムをする段に至って設計のクソさは怨嗟の対象であっても今更直せねーよという場合も多いわけで）。
あと、設計書のどの部分に相対するかのガイド的なコメントはプログラマー的には本来不要であるが、メンテフェーズにおいてクソみたいなスキルしかない要員がそれでも職責を果たそうと努力する際の指針としては大変重要なものになりうる。
つまり、一生自分（やその同程度の人員）でメンテナンスが可能なものについてはおおよそコメントが必要な事態は発生しない。ということは、そうではない仕事において、コメントを一切不要とする判断はメンテナンス性を損なっている仕事であると「見なされる場合がある」わけだ。もちろん、正しい保証が仕組みから担保できないコメントを100%信じる必要がある現場はクソだと思うが。

もう一つコメントが重要なのは、どういう理由かはさておき、妥協したことが可視化されている場合だ。この記事は以下の引用部分をヒントに書かれているが、これがいわゆる仕事ってやつだ（悲しい。

さて、いまを遡ること10年ほど前。
会社の先輩が一身上の都合で会社を退職していき、僕は先輩が担当していたシステムを引き継ぐことになりました。
で、そのシステムの改修をすることになったのでソースコードを見てみたら、システムの肝に近い部分にこんなコメントがあったんですよ。
// その場しのぎの処理。仕方がない。

【プログラミング】退職した先輩が書き残していったコメントがひどすぎる・・・ - 私の戦闘力は５３万マイクロです

ほんとこういうの書いておいてくれないと困る。書いてあった上で、見たことにするのか見なかったことにするのかを判断したいものだ。

参考エントリ

http://nzmoyasystem.hatenablog.com/entry/no_comment_culture
コメントを書かない理由 | おごちゃんの雑文