ソースコードにコメントは書かない！
高木です。おはようございます。
いきなり結論から書きますが、私はソースコードにコメントを書きません。
面倒だからということもありますが、主義として書かないようにしています。
もちろん、まったく書かないかというとそんなことはなく、デリケートなところには必ず書くようにしています。
あと、実装を後回しにするような箇所にもTODOコメントを書きますし、頻繁にそこに関わる場所には検索用のコメントも書きます。
それでも、原則は書かない主義なのです。
「他の人のために書くべき」という意見もあります。
そういったことは確かにありますが、その「他の人」がどういう人物かは重要です。
使用しているプログラミング言語の仕様や標準ライブラリ、典型的なデータ構造やアルゴリズムやイディオム、学校で習う数学などの一般教養に不自由がある人物に配慮する必要など一切ありません。
そのような似非技術者、似非プログラマーは半日以内に淘汰してしまったほうが、それこそ「他の人のため」になります。
ちなみに私が他人の書いたソースコードを読むときには、コメントを除去する作業から始めることも少なくないのです。
「日本語のほうが理解しやすい」という意見もあります。
そういうことをいう人たちは、プログラミングするとき一体何語で考えているのでしょうか？
プログラミングするときは、プログラミング言語で直接思考するのが当然だと思います。
日本語のコメントを読んで、それをわざわざプログラミング言語に翻訳するのでしょうか？
翻訳なんかしなくても、プログラミング言語でそこに既に書かれているというのに。
「英語は苦手だから」という意見もあるようです。
そもそも中学生レベルの英語ができない人物を相手にする必要があるのか、はなはだ疑問ではあります。
そこには目をつぶるとしても、英語が苦手なら日本語の識別子を使えばいいのであって、わざわざコメントを書く必要などありません。
素人が相手の場合は事情は異なります。
私はちょっとした試作や一点ものの開発を引き受けることがあります。
そうした開発では、客先で試行錯誤しながらパラメータを調整したいというニーズが多々あります。
その場合には、個々のパラメータがどのような意味で、どう修正すればいいのか、注意点は何かなど、詳細にコメントを書きます。
あくまでも素人向けだからです。
しかし、典型的なプログラミングでは素人に配慮する必要などありません。
冗長なコメントは、例えるなら、日本人にもかかわらず漢字が苦手な人向けに、すべての漢字にルビを振ってまわるようなものです。
当然生産性は著しく低下します。
このようにコメント不要論者の私ですが、きりのいい段階で大量のコメントを追加することはあります。
Doxygen等でドキュメントを自動生成したり、インテリセンスに対応したXMLコメントを入れたりするためです。
例えるなら、そういった作業は、ワープロで文字を修飾したり、罫線を入れたり、挿絵を挿入するようなものです。
ある程度内容が固まってからの作業であり、頻繁に変更が入る段階で、常に追従させるような作業ではありません。
コメントは書くのが当然といった風潮がまだまだあるのは事実です。
そのため、コメントがなくても理解できるソースコードを書く訓練、そしてコメントがないソースコードを読む訓練を受けていない人たちが多いのでしょうね。
だまされたと思って、コメントを一切書かずにコーディングする訓練をやってみてください。
きっと得るものがあると思いますよ。