英文スタイルガイド解説(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.)

7/25に試験システムのメンテナンス

7/25(土)の15〜16時頃に試験システムのメンテナンスが実施されるため、その時間内での受験はできません。

ベーシック試験、アドバンスト試験、および模擬試験のすべてが対象です。

受験を予定されていた方にはご迷惑をお掛けし、大変申し訳ありません。

正式版を開始

本日、「プログラミング英語検定」の正式版を開始しました。

ベーシック試験」と「アドバンスト試験」の2種類です。受験料はベーシック試験が2,500円、アドバンスト試験が4,000円です(いずれも税抜価格)。

どちらの試験にも模擬試験が用意されており、当面は毎月200名ほどを上限に無償で受験可能です。なお問題は終了したベータ版と同一です。

団体受験のモニター募集

団体受験のモニター(試用者)を募集しています。団体受験は、学校や企業において学生や社員のプログラミング英語力確認に活用できます。モニターに選ばれた場合、アンケート回答などを条件に、10〜50名分の本試験用受験チケットが無償で提供されます。詳細はこちらをご覧ください。締切は8月末です。

英文スタイルガイド解説(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.)

ベータ版提供の終了

2019年より提供してきた、プログラミング英語検定の「ベータ版」の提供を本日6/26をもって終了しました。

ベータ版受験時にアンケートにお答えいただいた皆さま、誠にありがとうございました。正式版の合否水準や試験時間などの設定で参考にさせていただきました。

当面は、代わりに「模擬試験」を無償で提供します。ただし問題内容はベータ版と同一です。

なお、正式版は2020年7月の提供開始を予定しております。公開日が確定したら、再度お知らせいたします。

英文スタイルガイド解説(7):数の書き方2

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

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

数の書き方(2)

URL:https://developers.google.com/style/numbers (2020-05-26閲覧)

前回取り上げた「数の書き方(1)」の続きです。

パーセンテージ

数字と記号(%)を使い、間にスペースは入れない(例:40%)。ただし文頭に置く場合、どちらもスペルアウトして(つづりで)書く。

 ◯ Forty percent of the files

数の範囲

ハイフンを使い、間にスペースは入れない。

 ◯ 2012-2016

日本語では範囲を示すのに「〜」(波ダッシュ)を使いますが、英語では使いません。特に形が似ているチルダ(~)は、英語では数字の前に付けると「約」や「およそ」の意味(例:「~40」で「約40」)となり、誤解の原因になりうるので注意しましょう。

桁区切りと小数点

アメリカの標準を使う。つまり3桁ごとの区切りにカンマ(,)、小数点にピリオド(.)。

 ◯ The limit is 1,532,784 bytes per day.
 ◯ $0.031611/vCPU hour

これは日本でも同じなので、なぜわざわざ説明するのか疑問に思われるかもしれません。実は、桁区切りにピリオド(または空白)を使う国や、小数点にカンマを使う国があります。例えば以下の通りです。

  • 日/米:1,234,567.89
  • ドイツ:1.234.567,89
  • フランス:1 234 567,89

寸法

小文字のxを使い、間にスペースは入れない。

 ◯ 192×192

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

YouTubeでプログラミング必須英単語を解説

プログラミング英語検定のYouTubeチャンネルを開設しました。

「プログラミング必須英単語600+」の一部英単語を1分で解説する動画を公開しています。これまで「プログラミング英語検定ニュースレター」(メール登録)で取り上げてきたベーシック300およびアドバンスト300の英単語です。こちらのページにも再生リストとしてまとめています。

新しい動画は定期的に追加する予定です。よろしかったらYouTubeチャンネルに登録してみてください。

英文スタイルガイド解説(6):数の書き方1

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


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

数の書き方(1)

URL:https://developers.google.com/style/numbers (アクセス:2020-04-29)

日本語でも、たとえば「二進法」なのか「2進法」なのか、数の書き方で悩むことがあります。今回は英語で書く際、スペルアウトするケースと、数字を使うケースとについて取り上げます。なお「◯」はGoogleが挙げる良い例です。

スペルアウトするケース

一般的に、次のケースではスペルアウトします(つづりで書く)。

  • 0〜9の数
    • 例:zero、one、five、nine
    • ◯ four options、five minutes、nine developers
    • ただし後述の「数字を使うケース」に挙げる例外は除く(例:バージョン番号の「version 3」)
  • 文の先頭の数
    • ◯ Fifteen directories are created.
      • → 「15」ではなく「fifteen」
      • 数字を文の先頭に置かないよう、構文を変える工夫が必要なことも
  • 数字が後に続く数
    • ◯ This procedure creates fifteen 100,000-byte files.
    • → 「15」ではなく「fifteen」
  • 大まかな数
    • ◯ You can specify thousands of combinations.
    • → 「1000」ではなく「thousand」

数字を使うケース

一般的に、次のケースでは数字を使います。

  • 10以上の数
    • 例:10、11、256
    • ※ ただし以下は10未満でも常に数字を使う。
      • バージョン番号(◯ version 3)
      • 技術関連の数値(例:メモリー容量、クエリー数)
      • ページ番号
      • 章や節などの番号
      • 価格
      • 単位が付かない数(例:数式中の数)
  • 10以上の数が登場する文で使われる、10未満の数
    • ◯  The menu contains 15 options but 6 of them are disabled.
      • → 「15」があるので「six」ではなく「6」。つまりスペルアウトを混ぜない
  • 負数
  • 分数(ほとんどの場合)
  • パーセンテージ
  • 寸法
    • ◯ 192×192
  • 小数
    • ◯ 0.3 inch
  • 範囲
    • ◯ 2012-2016

かなり細かいルールもありますが、少なくとも「0〜9はスペルアウトすることがある」という点は覚えておきたいところです。

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