なんの記事？

protobuf 公式の API Best Practices ドキュメントの自分なりの要約です。

あくまで翻訳ではなく、自分にとって理解し易いよう噛み砕いた要約を記載していきます。

なぜ読んだか・書いたか

仕事で Protocol Buffers を利用することが多く、
このレビューにおいてレビュアーとレビューイが共通の判断基準を持つことは、
コードの品質向上、チームの効率化、そしてプロジェクトの成功に大きく貢献します。

この判断基準として当該記事がよさそうだということで職場で話題となり、
読んだか？読んだよ！では味気ない。
よい機会 & とても長いので、全部俺カレンダーにてアウトプットしようという試みです。

以下から本文開始です。

API ベストプラクティス

将来性のあるAPIを正しく作るのは驚くほど難しい。
このドキュメントの提案は、長期的でバグのない進化を優先するためにトレードオフを行うものです。

この文書はプロトのベストプラクティスを補完するもので、Java/C++/Go やその他の API に対する処方箋ではありません。
コードレビューでこれらのガイドラインから外れているものを見かけたら、その作者にこのトピックを示し情報を広める手助けをしてください。

注意:
これらのガイドラインはあくまでガイドラインであり、その多くには文書化された例外があります。
例えば、パフォーマンスを重視するバックエンドを書く場合、柔軟性や安全性を犠牲にしてでもスピードを追求したくなるかもしれません。
このトピックは、トレードオフをよりよく理解し、あなたの状況に合った決断を下すのに役立つだろう。

殆どのフィールドとメッセージを正確に、簡潔にコメントしてドキュメント化しておくこと

あなたが書いた（あるいは修正したもの）は、その際に何を考えていたかを知らない人々によって継承され、使われる可能性が高い。
新しいチームメンバーや、システムについての知識がほとんどない人にとって役に立つ言葉で、各フィールドを文書化してください。

具体的な例をいくつか：

// 悪いコメント： Fooを有効にする設定
// 良いコメント： Foo機能の動作を制御する設定
message FeatureFooConfig {
// 悪いコメント： 機能が有効かどうか
// 良いコメント： hoge で Foo 機能が有効かどうかを示すフィールド。 hoge の FOO_OPTIN が設定されていない場合はfalseでなければなりません。
  bool enabled;
}

// 悪いコメント： Fooオブジェクト
// 良いコメント： APIで公開されるFooのクライアント向け表現
message Foo {
  // 悪いコメント： Title of the foo.
  // 良いコメント： ユーザーが入力した Foo のタイトルを、正規化もエスケープもせずに示します。
  optional string title [(max_length) = 512];
}

// 悪いコメント： Foo config.
//   最も有用なコメントが名前の再記述である場合、そのコメントは省略した方がよい。
FooConfig foo_config = 3;

このように各フィールドの制約、期待、解釈をできるだけ少ない単語でコメントします。

上記の例にはmax_lengthが記述されていますが、このようにカスタムアノテーションを使用できます。
※ bufbuild/protovalidate を採用した例では、以下のような書き方をします。

  optional string title = 1 [(buf.validate.field).string.max_len = 512];

時間が経つにつれてドキュメントはどんどん長くなります。長さは明確さを損ないます。
簡潔さを心がけましょう。