API仕様を書く（4）

（「API仕様を書く（3）」からの続き）

2017年8月末でリコーを退職して、ソラミツ社で働き始めました。技術的にはgRPCを使ったサーバー側の開発に加わることになりました。

gPRCに触れたのはその時が初めてですが、RPC（Remote Procedure Call）そのものは、Xerox社のCourierとよばれるRPCに1984年から接していましたし、後にSunのRPCを使ったツール開発（MessagingToolと分散コンパイルツール）も行っています。Courierは、XNS（Xerox Network Systems）の各種サーバーのプロトコルを記述するのにも使われており、プロトコル仕様はかなり丁寧に書かれていたと記憶しています。

gRPCは、RPCの定義を.protoファイルに書いてprotocでコンパイルしてスタブを生成します。RPCはその名前が示す通り、Procedure Callであり、Procedureを定義する訳です。呼び出しのパラメータ、呼び出し結果のレスポンスなどをstructとして定義します。また、エラーを通知するためにステータスコードを返すことができるようになっています。ステータスコードは、Javaに例えるとメソッドがスローする例外に相当します。

開発されていたサーバーのgRPCの定義である.protoファイルの中を見ると、何も書かれていませんでした。Javaで例えると、「公開APIのクラスやインタフェースの定義が書かれている.javaファイルに一切Javadocが書かれていない」という状態でした。

『Effective Java 第2版』を読まれたことがあるエンジニアであれば、そのようなクラスやインタフェースは公開APIとしては不適切であることは認識できると思います。『Effective Java 第2版』で該当する項目と章は以下の通りです。

• 項目44 すべての公開API 要素に対してドキュメントコメントを書く
• 第9章 例外

もちろん、『Effective Java』はJavaに関する内容なので、.protoファイルでは、そのエッセンスだけを適用して読み替える必要があります。簡単にまとめると、以下のことをAPI仕様として書く必要があります。

1. 各PRCの説明
2. 各PRCのリクエストパラメータとレスポンスパラメータの説明
3. リクエストパラメータの制約（事前条件）とそれに違反したときに返されるステータスコードの説明
4. RPC呼び出しの制約（事前条件）とそれに違反したときに返されるステータスコードの説明
5. RPCを実行したときに起きる可能性のあるエラーとそれに対して返されるステータスコードの説明

何も書かれていなかったので、サーバー側のシステムを理解することを目的として、私自身ですべての仕様を.protoファイルの中にコメントとして書きました。仕様を書きながら、不備も多く見つけましたし、gRPCを直接呼び出してテストするコードを書いて、必要あればサーバー側のコードを修正したりもしました。

上記の1.から5.までについては、次回もう少し詳しく書きたいと思います。

（続き）

API仕様を書く（3）

（「API仕様を書く（2）」からの続き）

私自身が開発のグループリーダーであった1701Gが組織として存在していた2013年7月から2015年5月までの期間を除けば、リコーでの8年間は、自分で何かを設計することは非常に少なく、誰かが設計したものをレビューすることが圧倒的に多かったです（残念ながら1701Gのときも、私自身はレビューやデバッグをすることはあっても、自分で設計や実装まで行うことは少なかったです）。

2009年9月にリコーで働き始めたのですが、当時はある大規模なソフトウェア開発がJavaで行われていました。しかし、ソフトウェア開発経験が浅いソフトウェアエンジニアが大量に投入されていて、誰も『プログラミング言語Java 第4版』も『Effective Java 第2版』を読んだことがない状況でした。それに加えて、マルチスレッドプログラミングが行われており、私がレビューしたほとんどのコードは間違っていました（「マルチスレッドプログラミングにおける重要な４要件」）。それで、やはりきちんと学習させる必要があるということで、リコーでもJava研修を始めることにしました。

1701Gの期間を除けば、様々なソフトウェア開発組織の新規APIのレビューやコードをのレビューを行っていたのですが、振り返ってみると、やはりAPI仕様を書くことは、多くの開発者が不得意としていたという印象があります。特に、NDAを結んで外部のサードベンダーに公開するSDKのAPIに関しては、使う側のことを考慮したAPIに出会うことは少なく、様々な修正を指導していました。

今から言えることは、きちんとしたAPI仕様を書かせるには、「場」である開発の現場で指導し続けなければならないということです。そして、「指導し続ける」には、以下の条件が揃っている必要があると思います。

1. 指導対象者のエンジニアより、開発組織内で高い地位にあること
2. 自分の部下を育成するという意味で指導を根気よく続けられること

同じ年代のエンジニアに何かを注意したり指導したりするのは、なかなか難しいです。さらに、別の組織やグループのエンジニアに対して指導するのはさらに難しいです。そのため、やはり1.が重要だということです。講演で、「どのようにして指導してきたのですか」と聞かれることがあるのですが、「開発部長としての立場で強制的に指導していました」と答えることが多いです。それは、API仕様を書くことだけでなく、テストファーストで開発することや、不具合が発生したら再現テストを最初に書かせるといったさまざまなソフトウェア開発の側面での指導が含まれます。

リコーでの最後の2年は、1.の条件は成立していなかったのですが、私のレビューを積極的に受けていたのは、その多くが私のJava研修の修了生達でした。

（続き）