☆☆☆はじめに☆☆☆
この記事は、個人開発 Advent Calendar 2017の2日目（12/02）の記事だよ。
前の記事は、kappy0322さんの『個人開発における開発プロセスを公開してみる (2017年冬)』だよ。
次の記事はturanukimaruさんの『ファイアーエムブレムヒーローズの戦闘結果計算ツールをKotlinでDDD的に作ってみた』みたい。
☆☆☆経緯とか☆☆☆
kappy0322さんから、Advent Calendarの招待を受けて、あれ、なんで招待されたのかな〜、とか戸惑いながら、
そういえば、前から書こうかなーって思っていた、コメントの書き方、この際だから書こうかな！と思い立って書くことにしたの。
ここで言うコメントって言うのは、ドキュメントコメントではないコメントのことね。
わたしは、プロの教育とか受けてないから、コメントの書き方も、当然、自己流なんだけど、
最近、いろんな人のソースコードを見る機会があって、
『何でこんなコメント書いてるの？』って思うのをいっぱい見てびっくりしたんだよね。たぶん、プロの人のも結構あったと思うんだけど……。
☆☆☆コメントの書き方の問題☆☆☆
で、どうも教育を受けたことがある人に聞くと、
『そのコードを書いた理由をコメントで書きなさい』
って、教えられているみたい。
実際に、ググってみると、本当に、理由を書きなさいみたいなのがいっぱい出てくる。
うん、いや、そうなんだけどさ、なんでそんな、てけとーな教え方してるの……？って思っちゃった。
いや、だってさ、こういうコメント書かれても困るでしょ。
// データが複数あるのでfor文で回す。
for(int i = 0; i < elements.length; ++i) {
// 略
}
// 処理を分けるために分岐する。
if(something.getID() > 0) {
// 略
}
極端な例ではあるけど、教えられたとおりに、『理由』を書いているよね。
でも、良いコメントだね！……ってならないよね？
だから、『理由を書く』っていうのは不十分だと思うの。
って、こういうところから、何が問題かとか、分析していってもいいんだけど、
わかっている人にはわかっていることだろうし、あんまりおもしろくないから、
その辺は省略して、わたしがコメントを書くときの考え方を紹介していくよ。
別に、書くのがめんどくさくなってきたとかそういうわけじゃない……から、ね？
あと、何度も書くけど、わたしはそういう系の教育受けてないから、これが本当によい方法かどうかはわからない〜。
いろいろ比較とか研究とかできるわけでもないし。
ただ、個人開発で困っている人に、少しでも役に立てば良いな、とは思っているよ。
☆☆☆すふぃあ流コメント術☆☆☆
最大のポリシーは、
『あとで変更するときの判断基準を書く。』
ということ。
だって、システムとかアプリケーションを、作って〜リリースして〜書き換えて〜ってやっていると、
コメントが必要な時って、『そういうとき』だよね？
このポリシーから、コメントを書く、より具体的な方針は、、
『普通ではない書き方をしたところには、その根拠を示す。』
ということになると思っているよ。
コメントを書いていないところは、コードそのままの意図で、おかしな動きをしていたら、それはバグとして直されたり、最適化されたりする。
コメントがあるところは、その妥当性をコメントをみて判断してから、変更や修正ができるってわけ。
たとえば、
// このメソッドの定義より、要素の最後には、○○を含めて返す必要がある。
// ○○は、××の特性を含むため、△△の処理は行ってはならないので除外されるように条件を調整している。
for(int = 0; i < elements.length - 1; ++i) {
// 略
}
return elements;
まぁ、サンプルだから、もっと別のコード書きなよっていうのはあると思うんだけど、そこはそれ。
でも、こうすれば、なんで-1しているの？？っていう理由と、それが妥当かどうかの判断ができるはず。
実は、この見解が間違っているとか、見解が変わったとかなら、よりどころとなっているコメントごと直すって感じ。
単に、『理由』ではなくて、変更するときの『判断基準』となることを書いていくのが重要ってこと。
ほんと、ただ、それだけだよ？みんなが知りたいことってそういうことじゃないのかな？
コメントが長くなるじゃん！って言うのもあるかもしれないけど、
必要なことは書くべきだと思うの。
くだらないことじゃないわけだからね。
かなり自分でも困ったソースコードの付近には、15行超えるようなコメント書いたこともあったかな。
まぁ、稀だけど。
読んで判断基準にならないコメントなんて、だからなんなの！って叫びたくなるだけじゃない？
☆☆☆弱点とか☆☆☆
この書き方の最大の弱点は、『普通』っていうのを共有しないといけないこと。
基本的には、必要十分なコードで、設計ポリシーにあっていれば問題は起きないはず。
裏を返すと、実力に大きな差があるチームだと、失敗すると思う。
まぁ、足手まといな人がいると、きっと別の意味で失敗するだろうから、大丈夫な気もするんだけどね。
その辺は想像だから、よくわかんない。
もう一つは、設計が微妙だとコメントがすっごく増えること。
だから、作っているときに気づいた、設計が微妙なところはすぐに直していかないとダメかも。
その設計がおかしいと言うコメントを大量に残すことになるからね。
って、この書き方じゃなくてもコメントが増えること自体は同じかもしれないけど。
☆☆☆よくありそうな質問と回答☆☆☆
Q. 難しいコードに説明コメントつけるのはどうなの？
A.
難しいって、普通じゃないってことでしょ？それは書き換える基準も含めてコメント書かないとだめじゃない？
まさか、難しいのが普通になって……ないよね？
もし、どこもかしこも難しくてコメントだらけになりそうって言うことなら、
それは設計がおかしいんだと思うよ。
Q. 必要なコメントが書かれていなかったら、困ったことになるんじゃないの？
A.
それは、つまり、書き換えるときに、必要な変更の判断基準が書かれてなくて、
さくさく書き換えた結果、間違った書き換えになっちゃうんじゃないか、って言うことだよね。
良いんじゃない？だって、前書いた人（過去の自分含む）さえ、それに気づいてなかったんでしょ？
気づけて良かったじゃない。
と言うだけだと思う。
てけとーに書かれていたのが、たまたま、動いていただけで、それが壊れるだけのこと。
壊れるのは、困るけど、それは、元を書いた人の問題だと思う。
このコメントの書き方をしていると、書き換える元にコメントを残さなかったことが悪いってことになんじゃないかな。
いや、まぁ、どっちが悪いとか言っても慰めにもならないんだけどさ。
なんか、どんなひどいコードでも、動いていれば正義みたいな考え方もあるみたいだけど、
それが『絶対』だとはわたしは思わない。もちろん、動いていることも大事だけどね。
動いていても、手抜きを許すわけじゃないし、ミスはありえることだと思う。
『過去のわたし！しっかりしろ！』って思うこと、よくある。
そこには、きっと、コメント以外の対策みたいなのが必要なんじゃないかと思ってみたりするよ。
Q. 書き直す予定がないときもコメント書くべきなの？
A.
書き直す予定がないって言うのは、バグが絶対にないってことかな。
それとも、バグがあったら、そのソースコードを全く参照しないで作り直すって言うことかな。
というわけで、そんなことは、まず、あり得ないと思うから、書いた方が良いと思う。
ただ、ちょっとしたスクリプトとかまで毎回書くかとかは知らないっ。
でも、やっぱり、あとでスクリプトを発掘すると、
あれ？これなんでこうなっているんだっけ？みたいなことは、わたしもよくあるけどね？（゜▽、゜
☆☆☆まとめ☆☆☆
さぁ、『理由』じゃなくて、『判断基準』をコメントに書いていってみようよ！
コメントを書くときに後の人のことを想像して考えることがやりやすくなるんじゃないかな。
わたしは、何にも責任とれないけどね！('-^*/
