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

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

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

APIリファレンスのメソッドの書き方(1)

URL:https://developers.google.com/style/api-reference-comments#methods (2020-06-28閲覧)

APIリファレンスの書き方に関するページから紹介します。今回はメソッド説明の書き方です。

メソッド説明の最初の1文には、その動作内容を簡潔に書きます。後続の文で以下の内容を説明します。

  • なぜ使うか
  • どう使うか
  • 呼び出す際の要件
  • 発生しうる例外の詳細
  • 関連するAPI

同スタイルガイドでは、Androidの「isChangingConfigurations()」メソッドの説明として、以下の例文を挙げています。

Checks whether this activity is in the process of being destroyed in order to be recreated with a new configuration. This is often used in onStop() to determine whether the state needs to be cleaned up or will be passed on to the next instance of the activity via onRetainNonConfigurationInstance().

まず1文目で「Checks whether …」(〜かどうかを確認)と動作内容を記述しています。続く2文目で「This is often used in …」と、メソッドを使う目的や状況を説明しています。

上記例文にあるように、メソッドでは文頭に動詞を使って処理を説明します。その際、次の動詞を用いるとしています。

  • ブール値を返す場合: “Checks whether …”
  • ブール値以外を返す場合: “Gets the …”
  • 戻り値がない場合:
    • 機能や設定をオンに: “Sets the …”
    • プロパティーを更新: “Updates the …”
    • 何かを削除: “Deletes the …”
    • コールバックなどを登録: “Registers …”
    • コールバック(典型的にはonで始まるメソッド): “Called by …”
  • クラス・オブジェクトを生成: “Creates a …”

こういったメソッド説明の冒頭などで用いる動詞は「プログラミング英語教本」(2-2-2)でも紹介しており、上記以外では次の動詞もよく使われます。

  • add(追加する)
  • construct(コンストラクターで生成する)
  • determine(判別する)
  • indicate(示す)
  • remove(削除する)
  • retrieve(取得する)
  • return(戻す)

(ライセンス表示: 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.)