1．今回の読んだ記事
No.17 コードに書けないことのみをコメントにする
著者: Kevlin Henney
2．記事の概要
コードに書いていないことではなく、書けないことをコメントにする
- コードにコメントをつけるのは理論的にはいいこと
- コメントを書くことにも文章術がある
- 不適切なコメントは見たものの集中力を削いだり、誤った情報を与える
- 一部の不要なコメントによって、重要なコメントまで読み飛ばされる可能性がある
- 読む人にとって価値のあるコメントとは、コードに書いていないあるいは書けないことである
3．この記事を選んだ理由・感想
理由
どのようなコードを書いたときにコメントが必要になるのか知りたいと思ったから。
コードにかけないことの具体的な事例をグループ内でディスカッションしたかったため。
感想
「コメントはたくさん書いた方が良い」という考えが変わった。
（不適切なコメントが作業者の弊害になりうるなど）
コードに書けないこととは、具体的にどのようなものがあるのか、疑問に思った。
4．議論
コードに書けないこととは何ですか？
- なぜ、こういう実装をしているのかを残しておくために使う
- 普通はやらないけれど、特別な意図があってやっている処理にコメントを書いた方がよい
- 以前見かけて役に立ったもとしては、ライブラリのバグなどに対応するための処理に対するコメントは書いてあって役に立った
必要なコメントとはどういうものなのか？
- 以前「このフェーズでは対応しない」というコメントを見たことがあるが、このようなコメントは必要ですか？
- こういったコメントはずっと消えないという可能性はないですか？
- TODOなどで書けばよいのでしょうか？
- こういった後々まで残る課題は、別で管理した方がよいと思う
コメントよりデバッグログに説明を書く
- コメントを書くより、デバッグログに書いた方が良いというアドバイスをいただいたことがある
- デバッグログに書くとテストの時や、異常系の処理などの時に役立ちそう
型が決まっていない言語の場合のコメント
- Pythonなどの型の決まっていない言語には書いた方がいいと思う
- 対して、Javaなど厳密に型が決まっている場合は見ればわかるのでコメントで書く必要はない
昔のソースコード
- 以前の現場は組み込み系で、変更履歴をコメントに書いていた
- 昔はたくさんコメントを書けと言われたけれど、今は無駄なコメントは無い方がいいと感じる
- （中年社員）そういうコードは懐かしいですね、ヘッダ部分にたくさん更新履歴が書かれていました・・・
まとめ
読書会4回目。
参加者の若手社員も読書会で話したことを業務で意識しているように思う。
何かしら学ぶことがあったのかなと感じた。
次回に続く。