「良いコードには多くのコメントがある」とコードの中にコメントを記述することの重要性をプログラマーは新人の頃から教え込まれます。しかし残念なことに「見苦しいコードには多くのコメントが必要になる」という、コメントが必要になる理由については教えられていないのです。
 |
アンドリュー ハント￥ 3,990
 |
HIROCASTERの経験から
SIer時代にコメントの重要性と言うより納品物としての必然性を教え込まれた記憶がある。例えば、こんなコメントは不必要である。
class foobar {
/**
* foobar class のコンストラクタ
*/
public function __construct() {
foo = array();
bar = array();
}
}「public function __construct()」と書かれているのにわざわざ上でコメントを書く必要性はない。同じ意味を違う言語(表現)で書いているだけだ。重複であるといってもよい。DRYの考えに反する。
でもこれ、ドキュメントを自動生成して納品物とする場合、クラスずつにページがあって、コンストラクタの場所にいろいろと書かれている場合と何も書かれてない場合とかってのは、納品物として白紙はまずいわけで、こういったコメントが必要だったりした。
そもそもコメントとは？
コメントとは、コード内に書かれたドキュメントである。SIerにとってドキュメントは納品物である。よって、先ほどのコメントは必要であったのかな。と今となっては思っているが、当時の上司や会社の方針だけの問題な気もする。
コードとコメントをDRY(*1)の考えで
さきほどの重複を防ぐためには
- 低水準の知識はコードに任せる
- 高水準な解説をコメントに書く
水準を分けることによって、コードを書いたらコメントも修正しなければならないという二度手間を極力防ぎます。ついついコードで書いたことをコメントに書いてしまいがちです。まずはそれをやめましょう。
- コードで意味していることはコメントに書かない = 低水準知識
- コードに書いていない必要なことをコメントに書く = 高水準知識
これがポイントです。
ブロックごとのコメント
メソッド内に3から5行ぐらいずつに1行開けてコードをわかりやすく書いていくかとおもいます。この集まりをブロックとしましょう。このブロックごとにコメントを書いていくプログラマーが時々います。そのメソッドは1スクリーン内に最初から最後まで収まっていますか？長くなっていませんか？
思い当たるコードがあったとすれば、それはメソッドの分割ができていない証拠です。1つのコメントで1メソッドできるのではないでしょうか？適切なメソッド名を割り当ててロジックを書けばそのコメントは不要ではないでしょうか？1スクリーン内にメソッドが収まり切らなくなったら警告信号が出ていると思ってください。
名前重要
コメントを記述しなくとも、適切な名前をクラス、メソッド、変数に割り当てていけば、意味を持ってくれます。プログラミング言語で書かれたロジックをのぞくことによって意味を持ったクラス、メソッド、変数の動きが見えてきます。そして意図が伝わってくるものです。
達人プログラマーは名前の重要性を良く理解している。
凡人プログラマーの僕としては、名前を変えることを面倒だと思ってはいけない。変更に変更を加え、違和感のない不動の名前を与えることが良きプログラマーとして必要なことなのだと考えます。
結論
コメントは不必要ではない。安易にコメントを追加することよりも名前を変えることによってすべてが解決することもある。コメントを追加する前に名前を変えることを考えてみてはいかがでしょうか。
*1: Don’t repeat yourself
