リーダブルコード 第5章 コメントをすべきところを知る 第6章 コメントは正確で簡潔に まとめ

第5章

コードからすぐにわかることをコメントに書かない

例）次のようなコメントは、コードを読めばすぐにわかるため不要

# profitに新しい値を設定する
void SetProfit(double profit);

# 2番目の`*`以降をすべて削除する
name = '*'.join(line.split('*')[:2])

初めてコードを見た人は、プログラムの全体像が分からない

初めてコードを見た人でも理解できるよう、ファイルやクラスには「全体像」のコメントを書く

コメントを書く作業

1. 頭の中にあるコメントをとにかく書き出す
2. コメントを読んで（どちらかといえば）改善が必要なものを見つける
3. 書きだしたコメントを改善する

第6章

コードの意図を書く

コードの動作内容をコメントするのではなく、このコードは何の処理のために行うのかの意図を書く

書いたコメントが長すぎたら、長いコメントを別の単語で表現できないかを検討する

（自力でコメントを置き換えることができる単語を調べられなかったら、生成AIに書いたコメントをそのまま送信し、1単語にできないか聞いてみるのもよいと思う）
例）
a.

このクラスには大量のメンバがある。同じ情報はデータベースにも保管されている。
ただし、速度の面からここにも保管しておく。このクラスを読み込むときには、メンバが存在しているかどうかを先に確認する。
もし存在していれば、そのまま返す。
存在しなければ、データベースから読み込んで、次回のためにデータをフィールドに保管する

b.
このクラスの役割は、データベースのキャッシュ層である

a. の「データの読み込み速度を早めるために、データベースに保管している同じ情報をこのクラスに格納する」といった説明を、
b.では「キャッシュ層」と一言で表している