はじめに
銃を抜いたからには 命を懸けろよ、nikkieです。
ミノ駆動本 11章「コメント」を機にいくつかの本をあたっています。
『Clean Code』の第4章「コメント」の読書ログを残します。
目次
『Clean Code』第4章「コメント」
Uncle BobによるCleanシリーズの1冊。
コメントの他にも命名や関数などなど、Cleanなコードを書くためのテクニックが紹介されています。
公開されている目次を引用します。
第4章 コメント
コメントで、ダメなコードを取り繕うことはできない
自分自身をコードの中で説明する
よいコメント
よくないコメント
参考文献
Uncle Bobが見たコードやOSSのコードのコメントを例に挙げながら、よいコメント／よくないコメントについて説かれる章でした。
基本スタンス：コメントは最小限
『Clean Code』のスタンスは「コメントは最小限にしよう」でした。
適切なコメントの使用方法とは、コードでうまく表現することに失敗したときに、それを補うのに使うことです。 (Kindle の位置No.1758-1760)
コメントは
との主張です。
この章はどんどんコメントを書こうという内容ではないです。
むしろUncle Bobはコメントを書くことを薦めていないように思われます。
コメントの代わりにコードで表現するという主張で、コードで意図を表現することが推されています。
例えば、処理にコメントを書く代わりに関数にして、関数名で意図を表現する2といったことです。
よいコメント
紹介されている例は限られており、コメントは最小限という主張を表しているように感じました。
気づきがあった例を紹介します。
- TODOコメント
- 好ましくないコードを放置するよりは、今は対処できないとしたTODOコメントのほうがよいという主張でした3
- 公開APIのJavadoc
- Pythonだとdocstringですね
- 「公開」というところがミソです（全部に書けばいいという話ではない）
よくないコメント
反面教師のコメントが多数紹介されます。
- nikkie感想：コメント書くからには 最善を尽くせよ4
コメントを書くのであれば、十分な時間をかけて、最善のコメントを残さなければなりません。(Kindle の位置No.1911-1912)
- コメント書くよりコードをきれいに
- コメントよりも関数や変数で表す
- コードと同じ情報量ならそのコメントは不要
終わりに
『Clean Code』第4章を読んで、「コメントって考えていたより重いのかもしれないな」と思いました。
実装した後にその処理の意味が伝わりづらいと気づいて、コメントを書いて対処することは私はよくあります（特に時間に追われているとき！）。
ですが、これは問題のあるコードをコメントで取り繕っているにすぎないのかもしれません。
最善を尽くしたコメントと考えると、もう気軽にはコメントを書けないですね。
一発で正解は難しいので後からよくすればいい5わけですが、コードと比べたらコメントの改善テクニックは自明でないように思われます。
むしろ（書籍が主張するように）コードの方が、後から修正しやすいために書きやすい気がします。
『Clean Code』は「コメントは最小限に」という主張でしたが、『リーダブルコード』や『読みやすいコードのガイドライン』はまた別の主張をしているように思われます。
「コメントに関して技術書の主張はバラツキがある」と感じ、いくつかの本を手にとっていますが、真逆の主張にも耳を傾けたいなと思いました。
P.S. ミノ駆動本_読書pyの予習
2/10(金)開催、ミノ駆動本_読書py事前準備の寄り道として、『Clean Code』第4章を読んだのでした〜
コメントに興味がある方のご参加お待ちしています。
短い章なのでさっと読めますよ〜
