リーダブルコードを読む part5
こんにちはかわです。
アドベントカレンダー２０記事目です。
前回の続きです。
5章 コメントすべきことを知る
コメントの目的は、書き手の意図を読み手に知らせることである。
- コメントするべきでは「ない」ことを知る。
- コードを書いているときの自分の考えを記録する。
- 読み手の立場になって何が必要になるかを考える。
1 コメントするべきでは「ない」こと
コードからすぐわかることをコメントに書かない
例 swift
//Humanクラスの定義
class Human{
private var age = 0
private var name = ""
//イニシャライザ
init(_ n: String,_ a: Int){
name = n
age = a
}
func hallo() {
print("Hallo")
}
//ageの値を返すメソッド
func Age() -> Int{
return age
}
//nameの値を返すメソッド
func Name() -> String{
return name
}
}
コメントのためのコメントをしない
コードからわかるコメントをしない
コードからわからないこと（処理の内部等）を記述（大切なことのみ）
ひどい名前はコメントをつけずに名前を変える
変数名やメソッド名等を変えることで理解が深まる際には、
コメントをつけず、変数名やメソッド名を変更する。
優れたコード > ひどいコード + 優れたコメント
2 自分の考えを記録する
思ったことややってみたことは積極的にコメントする
コメントをする際によく使う記法
| 記法 | 典型的な意味 |
|---|---|
| TODO: | あとで手をつける |
| FIXME: | 既知の不具合があるコード |
| HACK: | あまりキレイじゃない解決策 |
| XXX: | 危険！ 大きな問題がある |
上記の記法、チームの規約を作ることでコメントがわかりやすくなる
定数にコメントを付ける
定数を定義する際その定数が何をするか、
なぜその値にしたのかを記述した方がいい。
定数の「背景」を記述する。
3 読み手の立場になって考える
プロジェクト外の人から質問されそうなことを予測し、コメントを残す。
コードを見て間違う可能性のあるもの、他の人が見たら驚くことを
コメントに残す。
ソースコードを見ただけでは得られないこと（依存関係や実際やっている事）
はファイルにコメントを付ける。（短いもので大丈夫）
関数内部でも処理ごとで要約コメントを書く。
ー＞詳細を調べなくても関数の概要を理解できるようにするため
4 ライターズブロックを乗り越える
手順として以下を繰り返す。
頭のなかにあるコメントをとにかく書き出す
コメントを読んで改善が必要なものを見つける
改善する
以上を繰り返し行うことでコメントの質はあがっていく
