『リーダブルコード』 第7章 制御フローを読みやすくする

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

鍵となる考え:条件やループなどの制御フローはできるだけ「自然」にする。コードの読み手が立ち止まったり読み返したりしないように書く。

条件式の引数の並び順

よりも、

の方が読みやすい。

左側:「調査対象」の式。変化する。
右側:「比較対象」の式。あまり変化しない。

※個人的には、数学の記法(1 < 2 < 3)の流れで、不等号の向きを決め打ち(<)にすることが多いのだけど、等号・不等号も含めた包括的なルールとしては、「左が調査対象、右が比較対象」の方が良いかも。

あと、

というバグを防ぐために

とする記法(本書では「ヨーダ記法」と呼ばれている)は、現代のコンパイラは if (obj = NULL)と書くと警告を出してくれるので、過去のものになりつつあるとされているけど、コンパイラを介さないインタプリタ言語では現代でも実用性がある。

if/else ブロックの並び順

  • 条件は否定形よりも肯定形を使う。例えば、if (!debug)ではなく、if (debug) を使う。
  • 単純な条件を先に書く。if と else が同じ画面に表示されるので見やすい。
  • 関心を引く条件や目立つ条件を先に書く。

三項演算子

鍵となる考え:行数を短くするよりも、他の人が理解するのにかかる時間を短くする。

基本的には if/else を使おう。三項演算子はそれによって簡潔になるときにだけ使おう。

do/while ループを避ける

私の経験では、do-statement は、エラーや混乱の原因になることが多い。(中 略)私は条件が「前もって」書かれている方が好きだ。そのため、私は do- statement を避けることが多い。

関数から早く返す

ガード節

悪名高き goto

C言語以外では、goto はほとんど必要ない。

ネストを浅くする

ネストが増える仕組み:既存のコードの変更を少なくしつつ条件分岐を付け足す、といった場合に増えやすい

対策:変更するときにはコードを新鮮な目で見る。一歩下がって全体を見る。

実行の流れを追えるかい?

コードの流れを追いにくくする構成要素:

  • スレッド
  • 例外
  • 関数ポインタと無名関数
  • 仮想メソッド

『リーダブルコード』第6章 コメントは正確で簡潔に

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

鍵となる考え方:コメントは領域に対する情報の比率が高くなければいけない

コメントを簡潔にしておく

シンプルに説明できることをダラダラ書かない。

あいまいな代名詞を避ける

// データをキャッシュに入れる。ただし、先にそのサイズをチェックする。

// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。

歯切れの悪い文章を磨く

コメントを正確にする。

// これまでにクロールした URL かどうかによって優先度を変える。

// これまでにクロールしていない URL の優先度を高くする。

関数の動作を正確に記述する

// このファイルに含まれる行数を返す。

// このファイルに含まれる改行文字(‘n’)を数える。

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

関数・メソッドの機能を全て見せることのできる実例をコメントで示す。

コードの意図を書く

「名前付き引数」コメント

Pythonなど、名前付き引数をサポートしている言語の場合、以下のように書くことができる。

名前付き引数をサポートしていない言語では以下のように書くことで、引数の名前を示すことができる。

全ての関数に名前付き引数コメントを使用する必要は無いが、よくわからない引数には使ったほうがよい。

情報密度の高い言葉を使う

// このクラスには大量のメンバがある。同じ情報はデータベースにも保管されている。ただし、
// 速度の面からここにも保管しておく。このクラスを読み込むときには、メンバが存在してい
// るかどうかを先に確認する。もし存在していれば、そのまま返す。存在しなければ、データベー
// スから読み込んで、次回のためにデータをフィールドに保管する。

// このクラスの役割は、データベースのキャッシュ層である。

『リーダブルコード』第5章 コメントすべきことを知る

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

コメントの目的は、書き手の意図を読み手に知らせることである。

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

  • コードからすぐにわかることをコメントに書かない
  • ひどい名前はコメントをつけずに名前を変える

自分の考えを記録する

  • 「監督のコメンタリー」を入れる:コードの意図を説明する
  • コードの欠陥にコメントをつける:TODO, FIXME, HACK, XXXなど
  • 定数にコメントをつける

読み手の立場になって考える

  • 質問されそうなことを想像する
  • ハマりそうな罠を告知する
  • クラスやファイルに「全体像」のコメントをつける
  • ブロックごとに要約コメントをつける

「コードを理解するのに役立つものなら何でもいいから書こう」

ライターズブロックを乗り越える

  1. 頭のなかにあるコメントをとにかく書き出す。
  2. コメントを読んで(どちらかと言えば)改善が必要なものを見つける。
  3. 改善する。

『リーダブルコード』第4章 美しさ

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

コードの美しさの3つの原則

  1. 読み手が慣れているパターンと一貫性のあるレイアウトを使う。
  2. 似ているコードは似ているように見せる。
  3. 関連するコードをまとめてブロックにする。

なぜ美しさが大切なのか?

プログラミングの時間のほとんどはコードを読む時間なのだッ!

コードの整形について

本書では、以下のトピックがC++/Javaのコード例と共に議論されている。

  • 一貫性のある簡潔な改行位置
  • メソッドを使った整列
  • 縦の線をまっすぐにする

PHPer的には、PHP コードの整形はプログラマがやるべきことじゃないということで、IDEに任せてしまうのが一番。

幸い、PHPにはPSR-1/2というコーディング規約の「業界標準」があり、それに沿った整形を行うためのツール(PhpStorm等のIDE)も揃っている。

概念の整理について

  • 一貫性と意味のある並び
  • 宣言をブロックにまとめる
  • コードを「段落」に分割する

コードを意味のある並びにしたり、意味のある単位で区切ったりすると読みやすくなる。

個人的な好みと一貫性

一貫性のあるスタイルは「正しい」スタイルよりも大切だ。

『Web API デザインの鉄則』第4章 エラー表現とドキュメント

WEB+DB PRESS Vol.82

Web APIのドキュメントに明示する必要がある項目としては、次のような事柄が挙げられます。

  • 認可(Authorization)の方法、必要な権限(scope)
  • エンドポイントURLやHTTPメソッド
  • リクエスト形式
  • レスポンス形式
  • エラー表現
  • 説明やサンプル

エラー表現

主要なHTTPステータスコード

  • 2xx系(成功)
  • 3xx系(リダイレクト)
  • 4xx系(クライアント側のエラー)
  • 5xx系(サーバ側のエラー)

以下、本記事の著者が使っているステータスコードの使用例です。

2xx系

200 OK
  • エントリリソースの取得(GET)
  • コレクションリソースの取得(GET
  • エントリリソースを更新し、現在のリソースを返す(PUT, PATCH)
  • オーバーロードPOST/GETを行い、レスポンスボディを返す(POST, GET)
201 Created
  • エントリリソースの作成(POST)
202 Accepted
  • 非同期処理全般(POST, PUT, DELETE, PATCH)
204 No Content
  • エントリリソースを更新するが、現在のリソースは返さない(PUT, PATCH)

4xx系

400 Bad Request

クライアント側の汎用エラー

401 Unauthorized

クライアントが適切なAuthorizationヘッダを送ってこなかった場合

403 Forbidden

リクエスト形式も認可情報も妥当であるが、そのほかの何らかの理由によりアクセスが拒否された場合

409 Conflict

リソースの変更が不可能又は矛盾している

429 Too Many Requests

リクエストの回数制限などにひっかかる場合に用いる

エラー表現と標準仕様

HTTPエラー表現のRFCとしてhttp-problemというものがあります。

ドキュメントに図を活用する

PlantUMLというUMLモデリングツールについて紹介されています。UMLについてはあまり詳しくないので省略で…。

感想

RESTの基本の整理のように、初心者にも役に立つ部分がありますが、基本的には、「Web APIの設計のベストプラクティスを知りたい」という読者に最もフィットする記事だと思います。クローズドなAPIであれば、多少いい加減な設計でも、クライアント側との合意ができていれば問題ありません。しかし、多くのユーザーに提供するAPIの場合、設計が非常に重要になります。

RFCのようなパブリックな仕様に基づいたAPI設計や、JSON Schemaを使用したマシンリーダブルな仕様書の作成等、意識すべきポイントの勘所がおさえられていて参考になる記事でした。