FORTRANから始まって41年（５）

きちんとしたAPI仕様の作成能力

「API仕様を書く」でも述べていますが、振り返ってみると、ソフトウェアエンジニアとしては、プログラミングできることに加えて、書いているソフトウェアのAPI仕様をきちんと書く能力を身に付けることも重要です。

きちんとAPI仕様を書く際には、次の視点が求められます。

1. そのソフトウェアを使う人達が提供される機能を理解し、間違いなく正しく使えるかという視点
2. 将来保守する人達の理解を助けるという視点

1. は機能の説明だけでなく、防御的プログラミングの視点を盛り込んだ仕様が書かれている必要があります。2. は説明するまでもなく、将来保守する人達が仕様を理解できる必要があります。

仕様が書かれていない場合、作られたソフトウェアは技術的負債となります。そのようなソフトウェアの仕様を理解するには、実装のコードを読んで理解する必要があります。ライブラリやマイクロサービスのAPIであれば、不正なパラメータを伴う呼び出しがどのようなエラーを返してくるかを理解するために、実装のコードを読んで理解する必要があります。そして、時間をかけて理解したことは、実は間違っているかもしれまん。

実装を読んでコードを理解したとしても、しばらくすると忘れてしまい、再度コードを読む必要があるかもしれません。もっと悪いのは、仕様に書かれていないために、いつの間にか、返って来るエラーの種類が増えていたりすることもあります。

返済が非常に困難な技術的負債

技術的負債の中で返済するのが極端に難しいのが、「API仕様が全く書かれていないソフトウェアのAPI仕様を書くこと」です。これは技術的に難しいというのではなく、担当者の能力的に難しい部類の技術的負債です。

• API仕様をきちんと書く訓練を積んで来なかったため、そもそも技術的負債であると認識していない。
• 結果として、API仕様を書くモチベーションが担当者にないため、負債を返済するのは苦痛であり、本人の中では優先順位が低い。その結果、「時間が取れたら」と言い訳しても、本人の中では優先順位が低いため、決して「時間を取らない」という結果になる。
• 「技術的負債を返済したい」とエンジニアが言ったとしても、悪い設計の変更やひどいコードの修正だけが技術的負債の返済だと思っている人が多い。API仕様書は本人にとっては優先順位が低いことから、技術的負債の対象になっていなかったり、対象となっていても優先順位が低いため、結果として返済されることはない。

開発の最初からきちんとAPI仕様を書くことは、ソフトウェアエンジニアが身に付けるべき習慣であるべきです。最初に書いていれば、開発中に必要に応じて修正することは容易です。

2009年9月にリコーに転職して以来、さまざまなソフトウェア開発の現場でAPI仕様のレビューをしてきましたが、きちんとAPI仕様を書いている人達に会ったことはほとんどありません。