API仕様を書く（まとめ）：柴田芳樹 (Yoshiki Shibata)：SSブログ

https://yshibata.blog.ss-blog.jp/2018-11-19

「API仕様を書く」として私自身の過去の経験を書いたものを読みやすく並べてみました。ちょうど同じような内容が『A Philosophy of Software Design』に書かれていました。

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

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