元ネタというか刺激されたBlog群を、順不同で列挙。
http://d.hatena.ne.jp/miau/20090915/1253040365
http://d.hatena.ne.jp/kaorun55/20090909/1252468278
http://d.hatena.ne.jp/Nagise/20090908/1252421227
http://blog.livedoor.jp/dankogai/archives/50619039.html
http://blog.livedoor.jp/lalha/archives/50126803.html
http://proger.blog10.fc2.com/blog-entry-30.html
おいちゃん的結論は「コメントは書け。それも、山盛りで」。
あるいはもうちょっと正しくまとめると「コメントがなくてもわかるような美しいコードを書いた上で、それでもなおコメントはきちんと丁寧かつ適切に書け」。
まず「一人のエンジニア」として己をスキルを腕を磨く、という見地に立った場合「コメントは可能な限り書かないほうがよい」となります。
より正確には「コメントなんかなくても。誰がソースを読んでも"何をやっているのか"だけではなくて"なにをしたがっているのか"までわかるような、素晴らしくシンプルで自明の理な芸術的に美しいコードを書くこと」は、エンジニアとして「ひとつの目標にするに足りる」、素晴らしい方向性だと思います。
なので「一人のエンジニア」としての目標としては、「コメントを書かなくてもいいようなソースコードを書く」はtrueだと思うです。
ただ。業務においては、おいちゃん原則としてこれに「否」を唱えるです。
えと…もう一度前提条件を確認。
・誰が読んでも
・「何をしているかも」「何がしたいのかも」簡単に読み解けるほどに、簡素で美しい
ソースコードが書けること「を前提条件に」コメントはいらない、と書いてあるです。
で。
ンなソース、書けますか？ 現実問題として。
あなたが書いたソースコードは。それが「あなたに問題がある」のか「読む人のスキルレベルに問題がある」のかはともかくとして。現場の全員が(よりコレクトには「今後入ってくる全エンジニアが」)「完璧に理解できる」ようなソースだ、と、言い切れますか？
もちろん、上述で取り上げたBlogのいくつかで主張されている「コメントなんかなくたってわかるような美しいコードを書くことがより望ましい」ってのは非常によくわかるのですが。
ただ現実問題として「意識が遠くなったまま戻ってこれなくなりそうな」ソースコードを現場で多々見るにつけ。
ぶっちゃけたところ「(限りなくありえないに近い、という意味で)ユートピアのような状況だなぁ」とか思うですよ色々と。少なくとも「業務現場においては」。
だから。とくに「現場において」おいちゃんは言い続けるわけです。
「いいから山盛りでコメントを書け」と。
えと…より具体的には。
概ね、こんな感じでの作業工程を、おいちゃん自身は踏みますし、下の子達にも踏ませることが多いです。
・何をしたいか何を作らなきゃいけないのかを妄想する
・それがクラスだったりAPIだったりする場合、まず自分が「作成者」じゃなくて「利用者」として、そのクラスを使ったと仮定した「妄想コード」を書いてみる
・ワンブレイク。コーヒーなりお茶なりタバコなりお好みで。
・「妄想コード」を見直してみる。「なんかうざくない？」とか思ったら作り直し。でなければ次へ進む
＊とりあえずクラスの外枠だけ書いて、中身空っぽのメソッドだけ書いておく。メソッドには「こんなことしたい」ってコメントをあわせて書く。書式をJavaDocとかにあわせると、場所にもよるけど、喜ばれることも多い
・各メソッドで何をしたいかさせたいかについて、妄想をたくましくしてみる
・ワンブレイク。コーヒーなりお茶なりタバコなりお好みで。
＊各メソッドで具体的な処理内容を「使い慣れた母国語で」書く。より具体的には「こんなことして〜」「あんなことをして」「ここでこうやって」「最後こ〜なる！！」という妄想を殴り書く。妄想なので、間違っても「ここで変数iをインクリメント」とかいう現実を書いちゃいけない
・ワンブレイク。コーヒーなりお茶なりタバコなりお好みで。
・妄想に満ち溢れたコメントを読み返す。意味不明なら２つ前に戻る。「いいんでない？」って思ったら次へ
・実際にソースを書く。このタイミングで「やっべこれ忘れそうだわ」っていう諸々があったら、コメントを書くことを許可してさしあげてもよろしくってよ？*1
・ワンブレイク。コーヒーなりお茶なりタバコなりお好みで。
・テストをしてみる
・テストで合格が出たら次のタスクに進む。テストでこけたら、それが「ソースを書くタイミングでミスった」のか「そもそも妄想した(１メソッド内の)処理の流れ自体に問題があった」のか「さらにそもそもとして、クラス切りとかメソッド切りでしくじりやがった」のかを分析/相談してみる。で、必要な工程に戻る
素晴らしいですね実際に手を動かすまでに３回もコーヒーが飲める。お茶にしたり紅茶にしたり中国茶にしたりマテ茶にしたりすると気分が変わってまたよいものです。時にはハーブティーなんてのもよろしい感じですね。
おいといて。
この手順で進めると、いやでも「ある程度のコメント数」は期待できますし。
で、「＊」のタイミングで「技術的により上位の人間にチェックしてもらう」と、色々と面倒な手戻りも減るので安心です。
技術的に上位な人は、こゆチェックは嫌がらずに丁寧にやりましょう。最終的に自分の仕事が減らせるんだから、そのほうが。
「わかるように書く」も「わかって欲しい」も、気持ちとしては非常によくわかるのですが。
現実問題、大抵「出来てない」ので。したらとりあえず「がっつりコメント書いておいてもらってるほうがまだマシ」ってのが、おいちゃんのぶっちゃけた本音でしょうか。
おいちゃんがコメントを(比較的)丁寧に書く理由は簡単。
「読んだだけで、裏の意図(背景/哲学)までわかるようなソースコード」はまだ書けないし。
一方で「数時間前に書いたソースコード」とか、すっかり脳内から消え去ってるので。
「数時間後とか、明日以降とかの自分」という「他人」に「なにやってんのか」を申し送るために、コメントは必須なのですだよ orz
*1:なんのキャラだいったい
