リーダブルコードの一部要約 ２

引く続きリーダブルコードの要約をメモとして書いておこうと思います。

4.コメントの目的とは、コードの意図を読み手に理解してもらうこと

コメントすべきでは「ない」こと：

　・コードからすぐに抽出できること

　・ひどいコード(例えば、ひどい名前の関数)を補う「補助的なコメント」

　　→コメントを書くのではなくコードを修正する

記録すべき自分の考え：

　・なぜコードがたの他のやり方ではなくこうなっているのか(「監督コメンタリー」)

　・コードの欠陥をTOD:やXXX:などの記法を使って表す

　・定数の値にまつわる「背景」

読み手の立場になって考える：

　・コードを読んだ人が「えっ？」と思うところを予想してコメントをつける

　・平均的な読み手が驚くような動作は文書化しておく

　・ファイルやクラスには「全体像」のコメントを残しておく

　・読み手が細部に捕われないように、コードブロックにコメントをつけて概要をまろまとめる

　例)

    //  ヤバい。これはリストに重複があったら、面倒なことになる。

　→言い回しをもっと詳細な言葉に置き換える

　・「ヤバい」は「注意：これには気をつけて」という意味。

　・「これ」は「入力を処理するコード」という意味。

　・「面倒なことになる」は「実装が難しくなる」という意味。

　書き換えたコメントは以下のようになる。

　//  注意：このコードはリストの重複を処理できません。(実装が難しいので)

　コメントを書く作業は、3つの簡単な手順に分解できる。

　・頭の中にあるコメントをとにかく書き出す

　・コメントを読んで(どちらかと言えば)改善が必要なものを見つける。

　・改善する

5.小さな領域にできるだけ多くの情報を詰め込んだコメントを書くこと

　・複数のものをさす可能性がある「それ」や「これ」などの代名詞を避ける

　・関数の動作はできるだけ正確に説明する

　・コメントに含める入出力の実例を慎重に選ぶ

　・コードの意図は、詳細レベルではなく、高レベルで記述する

　・よくわからない引用にはインラインコメントを使う

　・多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔にする

7.コードの制御フローを読みやすくするためにできること

　・比較を書くときには、変化する値を左に、より安定した値を右に配置する

　例：while (bytes_expected > bytes_received)

    →　while (bytes_received < bytes_expected)

 　・if/else文のブロックは適切に並び替える。一般的には、肯定系・単純・目立つものを先に処理する。

　・三項演算子（? :）・do/whileループ・gotoなどのプログラミング構成要素を使うと、コードが読みにくくなることが多い

　・ネストしているとコードを追うのに集中力が必要になる。深いネストを避けるには「直線的な」コードを選択する

・早めに返してあげると、ネストを削除したりコードをクリーンにしたりできる