API仕様を書く（まとめ）

「API仕様を書く」として私自身の過去の経験を書いたものを読みやすく並べてみました。

• API仕様を書く（1）
• API仕様を書く（2）
• API仕様を書く（3）
• API仕様を書く（4）
• API仕様を書く（5）ー gRPC protoファイル ー
• API仕様を書く（6）ー gRPC protoファイル（2） ー
• API仕様を書く（7）

ちょうど同じような内容が『A Philosophy of Software Design』に書かれていました。

A Philosophy of Software Design

• 作者: John Ousterhout
• 出版社/メーカー: Yaknyam Press
• 発売日: 2018/04/06
• メディア: ペーパーバック

関連する章は、第12章「Why Write Comments? The Four Execuses」と第15章「Write The Comments First」です。第12章では、コメントを書かない理由として多くのソフトウェアエンジニアが挙げる理由について反証しています。第15章ではコメントを最初に書くことの有用性を説いています。ここでのコメントは、私が述べているAPI仕様に関する部分も含まれています。

翻訳はされないようなのですが、分かり易い英語で書かれていますので、ぜひ読まれることをお勧めします。