はじめに
リンクスタート！ nikkieです。
『良いコード／悪いコードで学ぶ設計入門』（通称ミノ駆動本1）の読書ログです。
11章「コメント」のログを残します。
目次
- はじめに
- 目次
- ミノ駆動本 11章「コメント」
- コメントと言えば、t_wadaさんのこのツイート
- 『リファクタリング』より、コメントもCode Smell
- コメントと言ったらこの本！『リーダブルコード』
- 終わりに
- P.S. ミノ駆動本_読書pyの予習
ミノ駆動本 11章「コメント」
公開されている目次を引用します。
11 コメント ―保守と変更の正確性を高める書き方―
11.1 退化コメント
11.2 コメントで命名をごまかす
11.3 意図や仕様変更時の注意点を読み手に伝えること
11.4 コメントのルール まとめ
11.5 ドキュメントコメント
読んでみて
- 11.1〜11.2がコメントにまつわる悪魔の解説
- 11.3〜11.4がコメントに関するミノ駆動さんの主張
- 11.5がドキュメントコメントの話題（Pythonではdocstring）
と理解しました。
コメントと言えば、t_wadaさんのこのツイート
コードには How
— Takuto Wada (@t_wada) 2017年9月5日
テストコードには What
コミットログには Why
コードコメントには Why not
を書こうという話をした
コードコメントには Why not を書こう
「なぜしないのか」「あえてやっていないこと2」を書く、ミノ駆動本と重なる部分もあるように思われます。
また、この中では「コミットログには Why」は結構意識するのですが、この4つは重ねていくほど効果がどんどん（＝指数関数的に）高くなりそうという印象です。
このツイートがどの程度普遍的なのか今の私には判断が難しいのですが、私の中にはこちらを言ってくれるt_wadaさんを置いています🦁
『リファクタリング』より、コメントもCode Smell
「リファクタリングの必要性を示す不吉な兆候」がCode Smell（＝コードの不吉な臭い）。
『リファクタリング』の3章で解説されています。
その中の1つにコメントがあるんです！
Code Smellとなるコメントは、消臭剤として（Code Smellを消す意図で使う）のコメントです。
ミノ駆動本の「11.2 コメントで命名をごまかす」は、消臭剤として使う一例と思われます。
『リファクタリング』ではCode Smellのコメントへの対処（どうリファクタリングするか）も解説されます。
例えば、関数の処理の一部を説明するコメントがある場合、「関数の抽出」で小さい関数に抽出し、説明コメントを消す（＝関数名として表す3）ことができます！
3章の以下の一節は、私としては非常に賛成できるものでした。
コメントは最小限にしたい派です（過激派）
コメントの必要性を感じたときにはリファクタリングを行って、コメントを書かなくとも内容がわかるようなコードを目指すこと。(Kindle の位置No.2542-2543)
コメントと言ったらこの本！『リーダブルコード』
『リーダブルコード』にはコメントを扱った章が2章あります。
5章 コメントすべきことを知る
6章 コメントは正確で簡潔に
駆け出した頃に読んだ部分ですが、色々な本に出会って立ち戻ってくるとまた印象が変わってくるものですね。
5章には「監督のコメンタリー」としてコメントを入れるのをオススメする部分があります。
ミノ駆動本の「11.3 意図や仕様変更時の注意点を読み手に伝えること」やt_wadaさんの「Why notを書こう」と重なる部分かと思います。
最初に読んだ頃は素直に試してうまくいったりいかなかったりしたのですが、いろんなコードを見てくる中で、いまの私には『リファクタリング』にある「コメントは最小限」という考え方がしっくりくるな〜と感じています。
終わりに
ミノ駆動本 11章とコメントつながりで思い出した書籍の読書ログをアウトプットしました。
コメントを扱った書籍は他にも浮かびます。
一度「コメント」という切り口で徹底的に情報収集しても面白いかもですね〜
現段階の感触ですが、今回紹介した中でもコメントについての共通理解といえる部分は見出せそうですが、それぞれのコンテキストにおける主張（バイアス）もいくらか載っているように思われます（結構バラバラですからね）。
銀の弾丸はコメントにもないのだと思いますが、自分が置かれているのとは別の文脈においては、コメントはどんなふうに捉えられるんだろうというのが気になるところです。
私の場合も、文脈が変わると（例：仕事で書くコードとOSSのコード）、コメントの使い方を僅かですが変えているように思うのです。
P.S. ミノ駆動本_読書pyの予習
1/27(金)改め2/10(金)開催、ミノ駆動本_読書py事前もくもくの一環として11章を読んだのでした〜
短い章なのでさっと読めますよ〜
