ちょいとネタがあったのと、まぁ色々教えるのにいずれにしても出てくる話なんで、ちょろりと。
ベースとして
■[プログラミング]コメントは補足説明
http://d.hatena.ne.jp/gallu/20101116/p1
を前提にいたしまするるる。
一言で片付けると「コメントってのは"後任者への申し送り事項"なので。お仕事である限り、ちゃんと書け」なのですが。
「コメントを書け」の側の主張は上述でやっているので、んでは「書かない人の言い訳」を、ここでは潰していこうかなぁ、っと。
コメント不要論ぶちかます方の主張を改めてまとめると
・コメント無くてもわかりやすいコードを書けるか、或いは書く事が必要である
→「コメントが無いと読めないコード」は駄目なコードである
・生産性が下がる
→駄目なコメントはかえって解析の邪魔になる
→コメントに「嘘」が書いてある事も多い
→メンテナンスがされないために、コメントが「昔は事実」であっても「今は嘘」になる
→コメントのメンテナンスに、更に余計な手間がかかる
→そもそも、コメントを書く手間自体が余剰コスト。コメントが無くてもコードを読めば理解できる
ってなあたりかと思われます。
つまり大別すると
・「コメントがなくてもわかりやすいコード」を書くべきである
・生産性が下がる
の、大体２系統。
「コメントがなくてもわかりやすいコード」については、 http://d.hatena.ne.jp/gallu/20101116/p1 で書いたのですが端的には
ただ。業務においては、おいちゃん原則としてこれに「否」を唱えるです。
えと…もう一度前提条件を確認。
・誰が読んでも
・「何をしているかも」「何がしたいのかも」簡単に読み解けるほどに、簡素で美しい
ソースコードが書けること「を前提条件に」コメントはいらない、と書いてあるです。
で。
ンなソース、書けますか？ 現実問題として。
あなたが書いたソースコードは。それが「あなたに問題がある」のか「読む人のスキルレベルに問題がある」のかはともかくとして。現場の全員が(よりコレクトには「今後入ってくる全エンジニアが」)「完璧に理解できる」ようなソースだ、と、言い切れますか？
もちろん、上述で取り上げたBlogのいくつかで主張されている「コメントなんかなくたってわかるような美しいコードを書くことがより望ましい」ってのは非常によくわかるのですが。
ただ現実問題として「意識が遠くなったまま戻ってこれなくなりそうな」ソースコードを現場で多々見るにつけ。
ぶっちゃけたところ「(限りなくありえないに近い、という意味で)ユートピアのような状況だなぁ」とか思うですよ色々と。少なくとも「業務現場においては」。
ここに集約されます。
まずは「自分と同等、ないしそれ以上の人間」が読んで「誰もが一撃で納得できるほどに美しいコード」がちゃんと書けているか。
次に「自分よりスキルの低い子」が、同じように読めるか。
すでにここで、十分以上に高いハードルが待ってるんですよねぇ。
で…もう一つ書きたいのは、その先。
以前にちょろりと、書いた事があるのですが。
■[プログラミング][その他技術]コメントのとらえ方の違い？
http://d.hatena.ne.jp/gallu/20071222/p1
*1
プログラムを読んで理解可能なのは、どこまでいっても「何をやっているか？」です。
そこには「実際の挙動」は含まれていますが、「その挙動に至る過程」とか「その実装を書いた意図」とかその辺は、当然ですが、推測は可能かもしれないのですが、書いてない以上「読み取る」事は出来ない訳です。
おいちゃんがよく「コメントには、何を"やっているか"ではなくて、何を"したいのか"を書け」っていう辺りの根っこですな。
「何をやっているか」はわかるんだけど「何をしたいのか」がそこから読み取れるとは限らない。
「だから」コメントが必要になってくるわけですね。
で…この辺はコメント不要派の人も「意図がややこしいときは書く」っていう話をするのですが、じゃぁ「どこまでが簡単でどこからがややこしい、の線引きはどこでするの？」というお話になってくるので。
その辺のさじ加減を「丹念に模索する」くらいなら「いいじゃんコメント書けよ」とか思うわけです。
別にコメント書いてデメリットが大してあるわけでなし。
…っていう話をすると当然出てくるのが「コメントを書くのも、読むのも、メンテするのも、無駄コストがかかるからそこを省きたい＝コストがかかる、というデメリットがある！」っていうお話で、つまりは「生産性が下がる」に繋がる、と考えられますんで、ここを切っていきましょう(切るとか言い切ったｗ)。
いやまぁ結論から書くと「問題視するほどのコストがかかるのかね？」という一言で終わるのですが、もうちょっとかみ砕いて。
実際問題として、「フロー状態に入って神が降りてきた」瞬間ってのはあるので。
そのときに、「コメントを書く手癖が付いていない人にとっては」、コメント無しで一気書きしたほうが「効率が良い」瞬間ってのは、これは間違いなくあります。ここは否定しない。
で、その時に「その瞬間ですら、コメントを随時差し込め」とも言わない。ンなインタラプトやったら「降りてきた神が霧散しちゃうから」。
ナニカが降りてきた瞬間は、一端、憑依されて神がかってトランス状態で「一気に書き下ろす」ほうが、間違いなくgoodです。
ただ。
「憑依状態一気書き」は、単純に「それが本当に正路なのか」を含めて、必ず後で読み返しをすると思いますし、してないんなら読み返せ。
その「読み返し」のタイミングでよいので、要所要所に、ちょいと丁寧に「コメントを入れる」癖を付けるとよいのです。
ちなみにそれをやると「神がかった時の自分の思考」を追うことが出来るので。
結果として「ある過去の時間軸で全力トランスで書けた」コードとおなじレベルのものを、ノーマル状態五分の力で書く事ができるようになるので、その時のトランス時には「更なるハイレベルコード」が書けるようになります。
上述のような流れでコメントを入れると、「コメントを入れる事自体」に関する手間コストは、無視出来る程度に「誤差」程度の量ですむと思われます。
そこで「結構な時間がかかる」んだとしたら、「コメントを入れる事自体のスキルが低すぎる」か「言語化できない程度に流れがぐちゃぐちゃで、何をやっているのか自分でも理解出来ていない程度に駄目ソース」なのかの２択。
後者は論外にしても、前者の場合は「書いてりゃ慣れる」んで、とっとと書きましょう。
もうちょっと補足すると…通常、人間は「自然言語で思考している」事が多いはずなので、その場合「思考している自然言語」を書けばよくて、後は「コメント用の日本語」はちょっとだけ訓練すりゃOK。
時々「直接コードで思考する」タイプがいるのですが*2。その場合は「他の人にレクチャーする」事を念頭に置いて、コメントを書きましょう。
後は「メンテナンス時は、ちゃんとコメントもメンテナンスする」で終了。
最後は「ここから見て取れる、よいコメントの書き方」。
まぁ上にも書いた通り「意図を書く(おいちゃんは「哲学を書く」って言い方をよくします)」で終了なのですが。
駄目コメントの、多分「殿堂入りしている」のが、これ。
$i ++; // 変数iをインクリメントする
うんゴメン見ればわかる。
これは明らかに、ゴミ。
コメントに書くのは「動作」じゃなくて「意図」。
つまり「インクリメントしている、っていう動作」じゃなくて「"なぜ"インクリメントし"たい"のか」を書くのが、コメント。
コメントは、言い方を変えると「後任者への申し送り事項」。
だから「こんな事を意図しているよ」っていうのを、ある程度丁寧に申し送ったほうが、単純に後で「自分が困らない」。
もちろんだから「そもそも自分が一回使うっきりのワンライナー」にコメントとか不要だし、実験コード的なミニマムコードにもコメントは不要。
だって「誰にも申し送らない」から。
ただ、お仕事で使うコードは「いつ何時、誰に渡すかわからない」ものなので。
その場合は、ちゃんと「申し送り事項」を必要な粒度で書くのは大事だと思うのですね。
なんていうコメント論を、つれづれっと。
