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

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

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

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

英文スタイルガイド解説(5):リストの使い方2

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


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

リストの使い方(2)

URL:https://developers.google.com/style/lists (アクセス:2020-03-19)

今回は、情報を見やすく整理するリストの使い方に関する第2回目です(1回目はウェブ上にも掲載)。

導入文

項目を列挙するリストの前には「導入文」を置きます。直後に項目を列挙する場合、導入文の末尾はコロン(:)とします。

良い例1:

Use the Submit button for any of the following purposes:
– To submit the form.
– To indicate that you’re done.
– To allow the next person to enter their data.

良い例2:

To get the USB driver, follow these steps:
1. Click Tools > Android > SDK Manager.
2. Select Google USB Driver, and then click OK.

良い例1を見ると「… the following purposes:」とあります。「following」は形容詞で「以下の〜」、名詞で「以下のもの」という意味があります。非常に便利に使える単語なので、ぜひ覚えておいてください。

また導入文は、それ自体で完全な文の形とし、各項目の末尾まで読んだら完全な文となるようには書きません(以下の悪い例)。

悪い例:

Use the Submit button to:
– Submit the form.
– Indicate that you’re done.
– Allow the next person to enter their data.

→ 1つめの項目の場合、「Use the Submit button to submit the form.」と末尾まで読んで初めて完全な文となる。そのため良くないとされる

項目内のピリオド

リストの各項目は大文字で書き始めます。また末尾にピリオドを付けるかどうかは、日本語でも悩ましいですが、Google開発者スタイルガイドでは大まかな指針を以下としています。

  • 項目が1つの単語で構成される場合、ピリオドは付けない
  • 項目に動詞が含まれない場合、ピリオドは付けない
  • 項目全体にソースコード用フォントが使われる場合、ピリオドは付けない

Googleによる例を見てみます。

良い例1:

The following words are adjectives:
– Big
– Small
– Gratuitous

良い例2:

You can do any of the following by using the API:
– Create an item.
– Replace one item with another.
– Update an item.
– Delete an item.

→ 動詞なのでピリオドあり。またここのfollowingは名詞で、常に単数形で使う(followingsとしない)

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

英文スタイルガイド解説(4):リストの使い方1

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


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

今回は、情報を見やすく整理するリストの使い方に関する第1回目です。

リストの使い方(1)

URL:https://developers.google.com/style/lists (アクセス:2020-02-18)

同スタイルガイドでは、リストの種類として以下の5つを挙げています。

番号リスト

順に実行する手順で使う。

例:

Here’s a sequence of steps to follow:
  1. Open the box.
  2. Remove the bobcat from the box.
  3. Feed the bobcat.

使うHTML要素:ol、li

文字リスト(アルファベット大文字)

選択肢(とりわけ択一)を示すのに使う。

例:

A. Java
B. JavaScript
C. Go
D. Dart

使うHTML要素:ol(”upper-alpha”)、li

中黒リスト

順序でも選択肢でもないもので使う。

例:

Here’s a list of things that can go wrong, in no particular order:
  ・Your bicycle might explode.
  ・The sun might go out.
  ・An ant might break its leg and require a tiny splint.

使うHTML要素:ul、li

説明リスト

用語と、その定義や解説というセットに使う(用語集)。

例:

Here are some descriptions of types of birds:
Emu
    The best kind of bird.
Crow
    The other best kind of bird.
Peacock
    Also the best kind of bird.
Phoenix
    An even better kind of bird.

使うHTML要素:dl、dt、dd

見出し中黒の説明リスト

スペースを節約しつつ、用語+定義などのセットに使う。見出しはボールド。

例:

Here are some descriptions of types of birds:
  ・Emu. The best kind of bird.
  ・Crow. The other best kind of bird.
  ・Peacock. Also the best kind of bird.
  ・Phoenix. An even better kind of bird.

使うHTML要素:ul、li


なお、項目を見やすく提示する方法としては「リスト」のほかに「テーブル」があります。どちらを使うかの判断基準として以下が挙げられています(リンク。2020-02-18アクセス)。

・各項目が1つのまとまり。例:プログラミング言語名一覧、手順
  → 番号リスト、文字リスト、中黒リスト(ol、ul)
・各項目がペアのデータ。例:用語と定義
  → 説明リスト(dl)
・各項目が3つ以上のデータ
  → テーブル

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

英文スタイルガイド解説(3):手順の書き方

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


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

今回は手順の書き方について、重要と思われるポイントをいくつか紹介します。

手順の書き方(Procedures)

URL:https://developers.google.com/style/procedures (アクセス:2020-01-19)

導入文

通常、手順の前に導入文を書きます。単に見出しを繰り返すのではなく、読者に状況を説明します。

導入文の直後に手順が来る場合、コロン(:)を使います。一方、導入文と手順と間に注などが入る場合、普通の文と同様にピリオド(.)で終えます。

導入文はそれ自体で完全な文の形にして書きます。

✕ To customize the buttons:
◯ To customize the buttons, follow these steps:

(◯は命令文として完全な文になっている)

ステップが1つの手順

ステップが1つだけの手順の場合、導入文の中に組み込みます。

✕ To clear (flush) the entire log, follow this step:
   1. Click Clear logcat.
◯ To clear (flush) the entire log, click Clear logcat.

操作が複数ある手順

一般的には、1つの操作に対してステップ1つとします。ただし細かな操作はまとめることが可能で、メニューの連続選択では「>」を使います。

◯ 1. Click File > New > Document.

その他のポイント

【A】まず目的を書いてから操作を書く(「節の順序」も参照)

✕ 1. Click File > New > Document to start a new document.
◯ 1. To start a new document, click File > New > Document.

例では「新規ドキュメントを始めるには」という目的が最初に置かれています。

【B】まず場所を書いてから操作を書く

✕ 1. Click File > New > Document in Google Docs.
◯ 1. In Google Docs, click File > New > Document.

例では「Google Docs」という場所が最初に置かれています。

【C】Pleaseは使わない

✕ 1. To open a document, please click File > Open.
◯ 1. To open a document, click File > Open.

英語の指示文では、pleaseなしの命令形が一般的です。

【D】省略可能な任意のステップでは最初に「Optional:」を付ける

◯ 1. Optional: Type an arbitrary string, to be delivered to the target address with each notification delivered over this channel.

【E】方向を示す言葉(例:above、below、right-hand side)で場所を指示しない。アクセシビリティーやローカリゼーション(翻訳)で問題が発生しうるため

たとえばアラビア語など文字を右から左に書く言語の場合、UI要素の配置位置も左右逆になります。そういった言語に翻訳されると、指示の場所が逆になります。

またパソコンとスマホで画面レイアウトが変わるようなレスポンシブなデザインでUIを作成した場合も同様の問題が発生する可能性がありそうです。

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

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

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


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

日時の書き方(Dates and times)

URL:https://developers.google.com/style/dates-times (アクセス:2019-12-19)

時刻

24時間での表記が要求されない限り、12時間での表記とします。

◯ 3:45 PM

このときの注意点は以下の通りです。

  • AMとPMは大文字にする
  • 時刻とAM(またはPM)との間に半角スペースを入れる

時間の幅はハイフンを使って「5-10 minutes」のように書きます。日本語では波かっこ(例:5〜10)を使うことがありますが、英語では使わないので注意しましょう。

日付

基本的に、月はスペルアウト(Janのように省略しない)し、年は2桁ではなく4桁で書きます。

◯ January 19, 2017

このような「月日年」の順序はアメリカ式です(イギリス式は「日月年」の順)。もし曜日を付ける場合は先頭に置いて「Sunday, February 12, 2017」とします。

月名や曜日名は省略しないのが基本です。たとえばMondayを「Mon」とはしません。ただし表のセルのようにスペースが限られている際に3文字での表記は可能です。その場合、先頭を大文字にし、末尾のピリオドは付けません。たとえばMondayなら「Mon」、Septemberなら「Sep」です。また3文字で略す場合は一貫してその表記にします。

✕ Mon, September 3, 2018(→ 省略とスペルアウトが混在)
◯ Mon, Sep 3, 2018

基本的に月名はスペルアウトして表記するとしていますが、数字のみで日付を書きたいケースがあります。このときはISO 8601に従って「yyyy-mm-dd」という形にします。

✕ 04/06/2017
◯ 2017-04-15

特に前者の「04/06/2017」のような書き方は、アメリカ式で読むかイギリス式で読むかで意味が変わってしまうため、避けた方がよいでしょう。

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

英文スタイルガイド解説(1):節の順序

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


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

節を書く順序(Clause order)

URL:https://developers.google.com/style/clause-order

ユーザーに対して指示文を書く場合、先に指示ではなく、条件(条件節*)を書くようにします。
Googleではまず以下の例を挙げています。

✕ See [リンク] for more information.
◯ For more information, see [リンク].

いきなり「See …」と指示を書くのではなく、「詳細情報が必要なら」と条件をまず書きます。次の例も同様です。

✕ Click Delete if you want to delete the entire document.
◯ To delete the entire document, click Delete.

いきなり「Click Delete …」という指示ではなく、「文書全体を削除する場合には」と条件を書くようにします。

こうすると、ユーザーは条件に該当しなければ、全文を読む必要がありません。

また、先に指示を書いておくと、ユーザーは条件を読まないまま、すぐ指示を実行してしまう可能性があります。特に2つ目の例の場合、文書全体を削除するという重大な結果につながる恐れがあります。

*「節」とは、文の構成要素中で「主語+述語」がある部分のこと。

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