英文スタイルガイド解説(9):メソッド説明の書き方2

本記事は「プログラミング英語検定ニュースレター #9」(2020年7月31日発行)からの一部抜粋です。同ニュースレターでは、検定の最新情報や英語解説を定期的に発信しています。登録はこちらから。

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.)