Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。

---

APIリファレンスのメソッドの書き方 ― 2

URL：https://developers.google.com/style/api-reference-comments#parameters （2020-07-30閲覧）

APIリファレンスの書き方に関するページから紹介します。前回はメソッド説明の書き方を取り上げました。今回はメソッドのパラメーターや戻り値などの書き方です。なお英語例文はGoogleのものです。

パラメーター

パラメーターの説明を書く際は、以下のガイドラインに従います。

• 大文字で書き始め、末尾にはピリオドを付ける
• ブール値でなければ、定冠詞（the）や不定冠詞（a）で書き始める
  • 上記例：
    • The ID of the bird you want to get.
    • A description of the bird.
• ブール値であれば、「If true/false, <命令文>」や「True if 〜; false otherwise.」といった構文にする
  • 例：
    • If true, turn traffic lines on. If false, turn them off.
    • True if the zoom is set; false otherwise.

簡潔な記述を目的としているため、主語と動詞がある「きちんとした」英文ではありません。そのため、慣れてなければ違和感を覚えるかもしれません。

また「True if 〜; false otherwise.」は「〜ならtrue、そうでなければfalse」という意味で、APIリファレンスに特有の表現です。otherwiseはプログラミング必須英単語600+のアドバンスト300に入っていますが、この構文での使い方が目立ちます。

戻り値

• ブール値以外であれば、「The …」で書き始める
  • 例：
    • The bird specified by the given ID.
• ブール値であれば、「True if …; false otherwise.」という構文にする
  • 例：
    • True if the bird is in the sanctuary; false otherwise.

ブール値以外は「The …」（定冠詞）とされていますが、実際には不定冠詞（a）で示すのが適当な戻り値もあります。

例外

• 見出しにすでに「Throws」という言葉があれば「If …」で書き始める
  • 例：
    • If no key is assigned.
• なければ「Thrown when …」で書き始める
  • 例：
    • Thrown when no key is assigned.

なおthrownはthrow（スローする。ベーシック300）の過去分詞形で、「スローされる」という意味です。

非推奨

メソッドなどが非推奨となった場合、文の最初にその旨を書きます。後続の文に理由や代替手段を書きます。

• 例：
  • Deprecated. Use #CameraPose instead.
  • Deprecated. Access this field using the getField() method.

deprecatedは「非推奨の」という意味の形容詞で、アドバンスト300に入っています。

（ライセンス表示： Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.）

---

[筆者紹介]