技術者の評価を下げる「悪い」コメントに注意しよう via おいっちょの日記

この記事を見ると「オレ間違ってのかー!NO---!」となる人多いんじゃないかな。みなさん、プログラムを書くとき、コメント書いてるでしょうか?僕は過去色んな人に「コメントはたっぷり書きなさい」と教わって育ちました。だから僕も昔は先輩諸氏の教えにそってコメントをたっぷり書いてました。少なくとも数行に1行はコメント。

でも今はほとんどコメントを書きません。どう頑張っても読み下せるコードなんて書けないアセンブラなら必須だけど、可読性最優先でコーディングできる環境なら必要ないと考えるからです。

まずコードを見れば明らかなところにコメントを書く必要はありません。これはコメントの整合性を保つための保守コストを上げるものでしかないでしょう。だからコードを読んで分かりにくいところにだけコメントを書くべきです。?、いや違う、コメントを書かなければ理解できないようなコードは整理するべきです。マーチン・ファウラーもコメントはリファクタリングすべき「不吉な匂い」として挙げています。処理内容をコメントで説明しているような状態は、すでに人間の理解範囲を超えた破綻状態のコードと言えるので、直すべきコードであることを判断する目安として便利です。きちんと整理されると、コメントは消えてしまいます。

メソッド単位の話をすると、まずメソッドはサッと読み下せるように書かれているべきです。もし処理が複雑で理解しにくいと感じたら、そのメソッドはアトミックに分解できる可能性が高いです。長すぎるメソッドや深すぎるインデントが目安になるでしょう。分解したメソッドにはコメントを補わないで良いように適切な名前を付けます。メソッドがアトミックに分解されると、アトミックメソッドを呼び出すフロー制御的なメソッドができます。このメソッドは容易に読み下せるはずです。オブジェクト指向でも、メソッドに仕事を詰め込みすぎにならないようにするために、パブリックメソッドの下は手続き型プログラミング的に整理してもいいんじゃないかと。パブリックメソッドの呼び出しを追えば処理の大まかな流れは理解できて、詳細を知りたい場合はプライベートメソッドまで目を通す。みたいな。メソッド名はコメントの代用になるため重要。分かりにくいと感じたらすぐに改名できるように、リファクタリング機能を備えたEclipseは便利ですね。

↑ただ、スキル的にそういうプログラミングができない人が書いたコードにコメントが無いと最悪なのは確かです。でもだからと言って「コメントを沢山書いておけ」と教え込むのは根本的に違うよね。

さて、元記事にある「作業予定」「無責任」は活用しても良いでしょう。頭にTODOとか書いておけばEclipseで一覧表示できるし、そうでなくてもgrepするだけでもかなり便利です。ただし「リリースまでに片付けるべき仕事」ですよ。

コメント

2005/6/ 9 18:03 from ジョージ

プログラム内のコメントですか。

私は条件分岐のところにコメントを書くことが多いです。
「~の場合は~をする」程度のものです。
それ以外はなるべく変数名で何のための変数だか分かりやすくしてるので、あえて細かくは書いてないです。

でもコメントをきっちり書いてあるのと、私のようにコメント少なめのプログラムでは、どちらが他の人に解析しやすいんでしょうかね?

2005/6/ 9 18:45 from みやまえ

条件式はコードでも普通1行のはずですからコメントは要らない気がします。それが必要だということは条件式が複雑すぎるのではないでしょうか。条件式を変数か、検査対象のメソッドに追い出すとスッキリする場合が多いです。

> でもコメントをきっちり書いてあるのと、
> 私のようにコメント少なめのプログラムでは、
> どちらが他の人に解析しやすいんでしょうかね?

コメントが要らないというのは、あくまでもコメントが無くても読めるように配慮して書かれたコードの場合です。

コメントをできるだけ書かないで済むようにコーディングすることで、綺麗なコードができていくと思います。コメントを書くとすれば、ロジックの中じゃなくて、メソッドやファイルのヘッダのほうだと思います。(ただし処理の手順ではなく、機能を書くこと)

2005/6/10 16:55 from ジョージ

なるほど、コメントが要らないようなコーディングですか。

メソッドのヘッダなどに機能概要を書いてたりしてた時期もありました。
前にいた制御系プログラムの開発する会社での話ですが・・・

今は会社のHPでASPを少し使うくらいなので、メソッドというような単位じゃなく、HTML内の動的部分でASPを使って表示してるくらいなので、少し勝手が違うのかもしれません。

2005/6/11 01:40 from 大槻昌弥

オンラインで流通させるパッケージで、仕様書まで添付しない場合は、コメントはモジュール仕様とかハードに依存している内容をメモするぐらいなら役に立つだろう。

プログラムの論理にコメントつけるなら・・・
「多分バギーである」とか「ネストが深いあるいは、結合強度が高く複雑」といった傾向・・・
つまりコーディングとしては端から失敗して泥沼状態に近いときに、豪くコメントばっかというようなファイルを作っているようなきがする(汗)
さらに泥沼にはまっていくのは、変更していく過程でコードとコメントの論理が矛盾してしっているようなファイルを作ってしまうコトねぇ。

もと記事にある指摘みたいなことは、初めてのプログラミングで30分ぐらいエディタと睨めっこしていたら気づくようなことだと思うけど・・・
まぁ、気づかない方はそれまでの人ってことなのかなぁ。

そういえば、「必要は発明の母」と言った方がいたようだけど、たぶん「問題に取り上げて変化を与えること」を「必要」というんだろうな。
私的には「何が問題なのか考えるのは物作りの原点」だと考えてます。

せめて意味不明なコメントは「変化を与えるモノ」であったと振り返ることができれば善しとしよう。(なんじゃいなぁ~それ)

2012/1/ 3 03:20 from ウェブサイトの昇進

私はあなたがこのウェブサイトで置いているすべての素晴らしいご提案に感謝するために購入の短評を書き留めるために必要。私の長期インターネットの検索では、一日の終わりに私の同僚との貿易に信頼性の詳細と技術で認識されている。私は読者が実際に洞察力にポインタを持つ非常にいくつかの優秀な個人との重要な場所に住んで真剣に幸運な私達のそのいくつかを主張するだろう。