【リーダブルコード】リーダブルコード第５・６章読んでみた

ご挨拶

前回の続きでリーダブルコードの第5・6章を読んでみたのでアウトプットしていきます！

リーダブルコードについて

エンジニアの必読書と書かれていたため、最初の一冊として読んでみることにしました。
この本の目標は「理解しやすいコードを書くこと」です！
気になる方は是非読んでみてください！
https://amzn.to/3Uinp1w

この記事の対象者

• コメントの付け方が苦手な方
• 理解しやすいコーディングを目指す人

第５章「コメントすべきことを知る」

• コメントするべきでは「ない」こと
• コメントすべきこと
• 読み手の気持ちを考える

それぞれ詳しく見ていきましょう。

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

• ひどいコードはコメントを付けるのではなくコードを変える
• コードを読めばすぐにわかるものはコメントにしない

例えば、以下のようなコードがあったとする。

// Accountクラスの定義
class Account{
  public:
    // コンストラクタ
    Account();
}

このような場合、全くコメントの意味がない。

通常は「補助的なコメント」が必要になることはなく、
「優れたコード＞ひどいコード＋優れたコメント」
という考えを肝に銘じたい。

コメントすべきこと

一言でいうと自分の考えを記録する内容である。

• 計算速度やエラー発生についても記述しておくことで再度試すことやテストの時間を短縮できる
• コードの欠陥にコメントを付ける（ex） //○○を使って整理した方が良い
• 定数にコメントを付けると良い場合が多い
• //TODO:　と書かれていれば後で手を付けるという意味を持つ

ここで、TODO関連の記法を示す。

記法	典型的な意味
TODO:	あとで手をつける
FIXME:	既知の不具合があるコード
HACK:	あまり綺麗じゃない解決策
XXX:	危険!大きな問題がある

読み手の気持ちを考える

• 要約コメントを書く
• 初めて読む人が詰まりそうな部分にだけコメントを書く

第５章まとめ

• コメントすべきでないこと
  • コードから推測が容易なもの
  • コードの改善余地があるもの
• コメントすべきこと
  • 自分の考えをまとめたもの
  • これからコードをどうしたいのかを書いたもの（ex）TODOコメント
  • 要約コメント

第６章「コメントは正確で簡潔に」

• 代名詞は使わない
• 入出力のコーナーケースに実例を使う
• コードの意図を書く
• 名前付き引数コメントを書く

それぞれ確認していきましょう。

入出力のコーナーケースに実例を使う

例えば、以下のようなコードがあったとする。

// 'src'の先頭や末尾にある'chars'を除去する。
String Strip(String src, String chars){}

この場合、以下のような疑問が生じる。

• charsは除去する文字列なのか、順序のない文字集合なのか？
• srcの末尾に複数のcharsがあったらどうなるのか？

そこで以下のように実例を交えてコメントを記述する。

// 'src'の先頭や末尾にある'chars'を除去する。
// Strip("aaba/a/ba", "ab")は"/a"を返す
String Strip(String src, String chars){}

コードの意図を書く

コードの処理内容を書くのではなく、なぜそれを実行したのかを書く。

// listを逆順にイテレートする
// 処理

上記のコメントは処理内容を書いただけのものである。
この場合は以下のように記述すると良い。

// 値段の高い順に表示する
// 処理

名前付き引数コメント

よくわからない引数については名前付き引数で呼び出す。
例えば、以下のようなコードがあったとする。

Connect(10, false)

上記のコードだと、10もbool値も何かわからない。
この場合は以下のように記述すると良い。

Connect(/*timuout_ms = */ 10, /*use_encryption = */ false)

第６章まとめ

• コメントは簡潔に書く
• 代名詞は使わない
• 入出力のコーナーケースに実例を使う
• コードの意図を書く
• 名前付き引数コメントを書く