リーダブルコードを自分なりにまとめてみた

リーダブルコードを自分なりの解釈でまとめました。

• 他人が最短時間で理解できることが大事

  • コードが短いことよりも理解しやすいことが大事。短くするために分かりにくくなってしまっては本末転倒

• 命名

  • 明確な単語を選ぶ
    • できるだけ、具体的な単語がよい
    • 類語辞典（シソーラス)などが参考になる
    • 変数名だけで何を指しているか、関数名だけで何をやる関数か分かる
      • getよりもdownloadやfetch
      • StopよりもKillやPause
      • sizeよりもMemoryByteやHeight
      • 汎用的な名前も避けた方がいいことがある
        • retやiなど
  • 変数名に単位など、重要な内容をを入れておいた方がいい
  • 必要以上に長くする必要はない
  • 変数のフォーマットを変えることでも情報を伝えられる
    • 大文字なら定数とか
  • 慣用的なもの
    • 限界値→max,min
    • 範囲→first,last
    • 包含、排他→begin,end
    • bool型→has,is,can,shouldなどを付ける
    • get,size→軽量なもののみに使う
  • どちらの意味にも捉えられるようなものはできるだけ避ける

• 見た目の美しさ

  • 改行などで、同じような部分は同じような見た目にしたい
  • 同じコメントが複数書かれているところは、まとめられるはず
  • 変数などを並べる順番も何かしらの規則性を持たせる
  • 処理ごとに段落に分ける
  • 変数の定義は、変数を使う直前で行う

• コメント

  • 変数名などによってコメントを付ける必要がないのがベスト
  • なぜ、どうしてその実装にしたのかを書く
    • 定数など、なぜその数字にしたのかも書く
  • コードの欠陥なども書く
    • TODO:後でやるべきことを書く
    • FIXME:直す必要がある部分を書く
    • HACK:あまりよくないけど、こんな解決策がある
    • XXX:重大な問題がある
  • 読み手が疑問に思いそうなことを予め書く
  • 処理を要約するようなコメントを書く
    • 詳細なコメントを書く必要がなくなるという副次的効果もある
  • コード見れば分かるじゃんってことは書かない
  • 関数を書く際の具体例とかを書くのもあり
  • 国語力！
    • できるだけ短い文章でできるだけ多くの情報を入れる
    • 正確に伝える
      • 行数を返す→\nの数を返す
  • インラインコメントを使うf(/*size =*/ 5)
  • プログラミングようの言葉を使う
    • キャッシュ、ヒューリスティック、ブルートフォース、ナイーブソリューション、正規化など

• 条件文、繰り返し聞

  • 変数を左に書く方がよい
    • x > 3
  • if elseでは単純な条件を先に書く
  • できるだけ肯定文にする
  • do whileは使わない
  • 関数ではreturnを使うことで見やすくなる
  • gotoは、関数内で最下層に置いたexitに飛ばすとき以外は使わない
  • ド・モルガンの法則を使う

• ロジック

  • ネストは浅くする

  • 使いすぎない方がいいものもある

    • スレッド
    • シグナル/割り込みハンドラ
    • 例外
    • 関数ポインタと無名関数
    • 仮想メソッド

  • 新たにメソッドを作ったり、格納する変数を作ることで、繰り返し出てくるコードが簡潔になるかも

  • 説明用に変数を入れる

    • is_locked = x && y == z
    • if(is_locked)

  • マクロを使うことでよくなることもある

  • 役に立たない一時的な変数はいらないかも

  • 変数のスコープをできるだけ縮める

    • メソッドをできるだけstaticにするのもあり
    • if( int x = a.b() )と書くことで、xはifブロックの中でしか使われないことが分かる

  • constを積極的に使う

  • 1つの関数に1つの処理（長すぎる関数を作らない）

    • 汎用的に使えるような関数ができたら、それ用のファイルを作っておくとプロジェクトの色んなファイルで使えていいかも
      • プロジェクト固有のコードから汎用コードを分離する
    • コードの本質でない部分は関数にまとめることで、処理を追いやすくなる

  • 一度に１つのタスクを行う

    • 行いたい処理を自然な複数のタスクに分割し、それを１つずつこなしていくコードが書けるのが理想
    • 複数のタスクを交互に切り替えたり入れ子になったりしない方がよい
    • 例えばwebページのタイトルとbodyをコピーする場合、「タイトルを見つけてコピー→bodyを見つけてコピー」よりも「タイトルとbodyを見つける→コピー」に

• 実装

  • 人間が考えてることをそのまま実装することで理解しやすいコードになる(もちろん、これが常にベストプラクティスではない)
  • 限られた条件でしか使われない昨日は、実際には必要ないかもしれない。必要になったときに実装すればよい
  • ライブラリやUnixツールボックスを使う
  • テストコードは、1つのテストケースを１つの関数で書けるようにするとテストの追加が簡単
    • check({テストに使う値},{expected num})のような関数を実装することで、check({1,2,3},{4,5})のようにテストケースを追加していける
  • テストコードのエラーは分かりやすく表示する
    • input, expected, outputがあると良い
  • テストコードに使う値も、最もきれいで単純なものがいい。関数の使用例を書くときの実引数と同じ
  • 後でテストを書くつもりでコードを書こう
  • 現実的にはカバレッジが100%になることはないし、100%にする必要は無い。
  • テストよりも実際のコードの方が大事だよ

• 他の人に見てもらうのもいいね

  • 読みにくくないか
  • 関数名を見て、どういう機能だと思うか