プログラミングにおける適切なコメントの書き方とは？

こんにちは、ShareWisの濱田です。ブログでははじめましてですね。
今回は開発におけるドキュメントやコードコメントの扱いについて話します。ここでいうドキュメントというのはサイトやアプリを作る上での仕様などを記したもののことです。
一般的な開発チームにおける仕様の記述場所には、以下のようなものがあります。

1. 紙媒体
2. ワードやエクセル
3. wikiなどのウェブページ
4. コード内のコメントのみ
5. ドキュメント?! そんなもん無いぜ。コードがドキュメントだ!!

1しかない、2しかない、あるいは4しか無いということは少なく、大抵は組み合わせて記述されます。
しかし組込みや業務システム向けのソフトウェアに比べてウェブサイトなどの仕様というのはある程度は流動的なところがありますので、1から3のようにコードから離れたドキュメントは敬遠されがちです。コードを変更してもドキュメントが古いままという事が起こるからですね。
そこで4のようにプログラムのコードにコメントとして説明が書かれます。
ところがこのコードコメントというのが非常に難しい。コードコメントに関して以下の様な言葉をよく聞きます。
「きれいなコードにはコメント不要」
この言葉が非常に誤解されやすく、これを聞くとついついコメントは出来るだけ書かないようにしよう!!という状態になりがち。確かにそうなんです。良くないコードコメントがいちいち動作の説明をしている、というパターン。そんな事はコードを読めば分かる。コメント無しでも動作が見えるコードを書けということですね。
ではコメントには何を書けば良いんでしょう？
私の意見としてコメントに書くべきことは、コードの背景や理由、動作の意図だと考えています。
曖昧な表現ですが、そのオブジェクトやメソッド、設定値がどのように使われているか、あるいは機能仕様との繋がりなどですね。
しかし、上記の事を意識するとコメントも冗長になりがちでそのバランスが難しい。
そこでやはり、冒頭1から3のような仕様書も必要かと思います。
何故こんなことをブログに書いたかというと、このようにドキュメントやコードコメントに気を配らないと新規開発メンバーの参加ハードルが非常に高くなってしまうため。
仕様書や上手なコメントが無ければ、コードからは局所的な動作の把握しか出来ず、サイト上の動作とどう関係しているか分かりにくくなりますからね。今後はコードそのもののクオリティ向上とともに、このようなドキュメントやコメントにも気を配っていこうと取り組んでいます。
この辺りは今後も試行錯誤して、当ブログで話していければと思います。
ブログも簡潔に書くように頑張ります。それでは。