『リーダブルコード』第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を使用したマシンリーダブルな仕様書の作成等、意識すべきポイントの勘所がおさえられていて参考になる記事でした。

『Web API デザインの鉄則』第3章 インタフェース設計

WEB+DB PRESS Vol.82

Web APIのインタフェースを定義する際に決めなければならない点は以下になります。

  • エンドポイントURI
  • HTTPメソッド
  • クエリパラメータ

エンドポイントURIの定義

ROA(Resource Oriented Architecture)におけるリソースは、URIを持つ必要があります。

エンドポイントURIとは、個々のリソースの所在を表すURIです。

前回に引き続き、本記事ではブログポストのリソースの扱いを題材にしていきます。
(オリジナルの記事ではメールのドメインリソースを題材としています)

すでに存在するリソースを返すエンドポイント

  • GETメソッドでアクセスできる
  • リソースの表現はapplication/json形式
  • /api/posts:複数のpostsリソースを取得(コレクションリソース)
  • /api/posts{/posts_id}:単一のpostsリソースを取得
  • /api/posts{/posts_id}/comments{/id}:ポストに関連するコメントを取得する(エントリリソース)

新しいリソースを作成するエンドポイント

  • POSTメソッドでアクセスできる
  • リソースの表現はapplication/json形式
  • /api/posts:新しいpostsリソースを作成

すでに存在するリソースを削除するエンドポイント

  • DELETEメソッドでアクセスできる
  • 削除が成功した場合は204 No Contentで応答する
  • /api/posts{/posts_id}:単一のpostsリソースを削除

HTTPメソッドの選び方

RESTにおいてよく用いられるHTTPメソッドは次の4つです。

  • GET(リソースの取得)
  • POST(リソースの作成)
  • PUT(リソースの更新)
  • DELETE(リソースの削除)

POSTを利用するケース

a. コレクションリソースに対して新規のエントリリソースを追加
b. 既存のリソースに対して状態を追加
c. オーバーロードPOST

aとbが一般的な利用方法です。

cのオーバーロードは、「ROAの用途では表現しきれないインターフェースを持つもの全般を表現するために用いる手法」です。具体的には、リソースの差分更新などに使用されます。

PUTを利用するケース

a. 既存のエントリリソースを更新
b. 新規のエントリリソースを(明示的に)追加

aは既存のリソースに対する差分更新ではなく置き換えだという点が重要です。PUTメソッドによる更新の際は、置き換えるべきリソースの完全な表現をリソースに含める必要があり、一部分だけを更新することはできません。完全な表現が含まれるからこそ、PUTメソッドの冪等性があるといえます。

差分更新については、PATCHという新しいHTTPメソッドがRFC5789で提案されており、Rails4でも採用されています。

コレクションとクエリパラメータ

コレクションリソースを取得する場合、エントリを何らかのリストとして表現する必要があります。こういったコレクションに対しては、取得件数や並び順、検索条件などを取得時に指定したいことがあります。

クエリパラメータが必要なケース

コレクションリソース全体を取得すると膨大な量になってしまうような場合には、ページネーションが必要となります。

ページネーションのためには、以下のようなクエリパラメータが必要です。

  • コレクション取得の開始位置(OFFSET)
  • コレクションの最大取得件数(LIMIT)
  • コレクションのソートフィールド(ORDER BY)
  • コレクションの並び順(ASC/DESC)