リーダブルコードを読む part6
こんにちはかわです。
アドベントカレンダー２１記事目です。
前回の続きです。
6章 コメントは正確で簡潔に
コメントは領域に対する情報の比率が高くなければならない
1 コメントを簡潔にしておく
少ない領域ですむように推敲する
2 曖昧な代名詞を避ける
代名詞はなるべく避けるように努める。
代名詞が何を指すかを明確にすべし。
3 歯切れの悪い文章を磨く
語彙力を磨く
4 関数の動作を正確に伝える
なるべく詳細に伝える。
コメントを読む人の誤解を減らすため。
5 入出力のコーナーケースに実例を使う
コメントが長文になる際には実例を使うべし。
ただし、簡単な実例では役に立たないので、
想定される質問に応えられる実例を書く。
6 コードの意図を書く
コードの動作をそのまま書くのではなく、高レベルから説明するのもあり。
その結果、コードが作者の意図に反しているかどうか見つけやすくなる。
7 「名前付き引数」コメント
これはコメントのような効果があるため使ったほうがいい。
Connect(/* timeout_ms */ 10);
8 情報密度が高い言葉を使う
説明が長くなった場合、専門用語等を使用して短くできないか検討する。
以上
リーダブルコードを読む 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 ライターズブロックを乗り越える
手順として以下を繰り返す。
頭のなかにあるコメントをとにかく書き出す
コメントを読んで改善が必要なものを見つける
改善する
以上を繰り返し行うことでコメントの質はあがっていく
以上
リーダブルコードを読む part4
こんにちはかわです。
アドベントカレンダー１９記事目です
以下の続きです。
4章 美しさ
- 読み手が慣れているパターンと一貫性のあるレイアウトを使う
- 似ているコードは似ているように見せる
- 関連するコードはまとめてブロックにする
1 なぜ美しさが大切なのか？
見た目が美しい方が使いやすい
ー＞プログラミングの時間のほとんどはコードを読む時間だから
流し読みしやすいコードを心がける
2 一貫性のある簡潔な改行位置
一貫性をもたせるために適切な位置に改行、コメントも整列させる
3 メソッド使った整列
同じメソッドを引数を変えて複数使っている場合、
ヘルパーメソッドを使用することでコードを整形し直した。
この章の例では変更の効果として、
- 重複を排除したことでコードが簡潔に
- 重要な部分が見やすくなった
- テストの追加が簡単になった
見た目を良くすることは表面上の改善だけではなく、
コードの構造も改善できる。
4 縦の線をまっすくにする
例
//hoge(a, b, c) a:String b:Int c:float という関数があるとする。
hoge("hello", 500 , 1.2)
hoge("world", 4000, 3.14)
hoge("kawa" , 10 , 109.8)
//二番目、三番目の引数がわかりやすくなる
縦の線が「視覚的な手すり」になれば流し読みがし易い効果がある。
似ているコードは似ているように見せる効果がある。
5 一貫性と意味のある並び
コードの並びがコードの正しさに影響することは少ないが、
ランダムに並べるより、意味のある順番に並べるべき場合もある
- 対応するHTMLフォームの
<input>フィールドと同じ並びにする - 「最重要」なものから重要度順に並べる
- アルファベット順に並べる
以上の並べ方がある
また、一連のコードでは同じ並び順を使うべし
email = "・・・・@・・・.com" phone = "0123456789" url = "・・・.com" print(phone) //この順番だとあとでわからなくなる print(email) print(url)
6 宣言をブロックにまとめる
宣言をする時、
メソッドの働きごとに分けて宣言することで、
概要が把握しやすくなる
7 コードを「段落」に分割する
コードの機能ごとに段落を作るべし。
その際にコメントを記入するとコードをざっと目に通しやすくなる。
8 個人的な好みと一貫性
個人的な好みがコードに反映される場合がある。
class hoge{
・・・
}
class hoge
{
・・・
}
どちらを選んでもいいが、
２つのスタイルを混ぜてしまうと読みにくくなる
スタイルを一貫することが大事
