リーダブルコードを読む 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
{
・・・
}
どちらを選んでもいいが、
２つのスタイルを混ぜてしまうと読みにくくなる
スタイルを一貫することが大事
以上
2017年 反省
こんにちはかわです。
アドベントカレンダー25記事目になるはずだったものです。
去年立てた目標を見ながら反省していきたいと思います。
コンテストで賞をとる
コンテストや大会にはいくつか出ました。
その中でも飛行ロボコンの自動操縦部門で２位になれたので達成ですかね。
勉学に対して意識を高め、理解力UP
耳が痛い話ですね。
言い訳をすると今年は去年より忙しかった気がします。
もっと勉強に精進すべきですね。
専門科目が少しわからない部分があるので勉強したいと思います。
良い、やってみたいことはすぐ行動する
行動しました。
むしろやりすぎてきつかったので、
自分のペースで挑戦していきたいと思います。
インターンも数社行かせていただきました。
勉強会にも行かせていただきました。
現在もプロジェクトに入って作らせていただいてます。
今年は今までよりも充実していたと思います。
しかし、身になったかと言われると微妙な感じがしています。
来年は今まで体験したことを身につける。
自分の能力を高めていきます。
感謝を忘れない
う〜ん
う〜ん
もっともっと日々感謝していきます。
こんな感じですね
いろいろなことに挑戦したのはいいものの、
どれも中途半端になってしまったという感じです。
来年は自分のinputとoutputを意識して行動していきたいと思います。
来年の目標
- 一年で技術系の記事１００個
- わからないことはすぐ調べる、行動する
- 自分が作りたいと思ったものはすぐ作成
- 感謝の気持ちを忘れずに
以上を目標として日々精進していきたいと思います
今年自分に関わってくださった方全てに
この場を借りて感謝の気持ちを伝えさせていただきます。
ありがとうございました。
来年もよろしくお願いします。
余談
去年のpokemon Go の図鑑
今年のpokemon Go の図鑑
たくさん捕まえました。
来年も捕まえていきます
