英文スタイルガイド解説(16):引用符の使い方

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

引用符の使い方

URL: https://developers.google.com/style/quotation-marks (2021-2-25閲覧)

今回は引用符(クォーテーション・マーク)です。二重引用符(ダブル・クォーテーション・マーク)と一重引用符(シングル・クォーテーション・マーク)の2種類があります。なお英文サンプルはGoogleのものです。

引用符とカンマ/ピリオド

イギリス英語では、カンマやピリオドは引用符の外に置かれます。一方でアメリカ英語では引用符の中に置かれます。たとえば次のような形です。末尾に注目してください。

  • イギリス式:See the section titled “Care and feeding of the emu”.
  • アメリカ式:See the section titled “Care and feeding of the emu.”

このアメリカ式は論理的ではないという批判があるようです(上記例の場合、ピリオドは文全体に関係するので、引用符の外に置くべきという考え方)。ただし慣習的にアメリカ式は広く使われているという理由で、Googleのスタイルではアメリカ式を使うとしています。

しかしプログラミングにおけるキーワードなどで、引用符内の文字そのものを示したい場合、カンマやピリオドは引用符の外に置くとしています。ただしソースコード用フォントを使う場合、引用符では囲みません。

  • ✕ If you enter “escape,” the program crashes.
  • ◯ If you enter “escape”, the program crashes.
  • ◎ If you enter escape, the program crashes.(※ escape部分のフォントが違う)

直線型と曲線型

引用符には、直線型と曲線型があります。Googleのスタイルでは常に直線型を使うとしています。

※ 注:表示フォントの関係でどちらも同じに見えているかもしれません。

  • ✕ The section’s title is “Care and feeding of the emu.”
  • ◯ The section’s title is “Care and feeding of the emu.”

直線型を使う理由として、以下を挙げています。

  • 曲線型は左用(“)と右用(”)を間違いやすい
  • ソースコードでは直線型が必須
  • 開発用ツールでは直線型を曲線型に自動変換しない

一重引用符を使う場面

Googleスタイルガイドでは、以下の場面で一重引用符を使うとしています。

  • 一重引用符を使うプログラミング言語のコード例
  • 引用符内で使う場合(入れ子)

後者の場合、アメリカ式では、上位レベルで二重引用符を使い、下位レベルで一重引用符を使います。以下の形です。

  • ◯ She said, “I heard him shout ‘Help,’ and saw him floundering in the water.”

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(15):コロンの使い方

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

コロン(:)の使い方

URL: https://developers.google.com/style/colons (2021-1-27閲覧)

基本的な使用方法

コロンは日本語表記であまり馴染みがない上に、英語母語話者でも使い方に悩む句読点です。たとえばノースカロライナ大学の資料では、以下を基本的な使用方法として挙げています。

  1. リスト、名詞/名詞句、引用、例/説明を導く
    • つまりコロンの直後にこれらが示される
  2. 文どうしをつなげる
    • 2文目が1文目の要約や説明になっている
  3. 時刻やタイトルなどで慣習的に使う

3番目は「12:45」(時刻)や「Terminator 2: Judgment Day」(映画のタイトル)のような形で使われ、それほど難解ではありません。一方、1、2番目は悩むことがあります。

ただしプログラミング英語を書く際によく使うのは1番の用法で、実際にGoogleスタイルガイドでも1番を想定した例文になっています。中でも最初の「リスト」を導くケースは使う場面が多いでしょう。そこで以下でも、リストを導くケースを想定して説明します。

コロンの前は完全な文に

リストを導くコロンは、完全な文の形(独立節)にします。例文はGoogleのものです。

  • ✕ The fields are:
  • ◯ The fields are defined as follows:

後者にリスト項目A〜Cを補うと、全体としては次のようになります。

The fields are defined as follows: A, B, and C.

AやBが短い言葉であれば、上記の書き方で問題ありません。ただしAやBに長い文や複雑な文などが入る場合は、次の形の方がユーザーは読みやすくなるでしょう。

The fields are defined as follows:
– A
– B
– C

また、例文にあるように、リストを導く際に「follow」という単語がよく使われます。上記の「〜 as follows:」に加え、「The following are 〜:」などの形がよく見られます。詳細はこちらの記事をご覧ください。

文中のコロンの直後は小文字

通常、文中で使うコロンの直後では、単語を小文字で書きます。

  • ◯ When you add or update content to an existing project, remember to take these steps: review the style guide; use checklists; enlist a fellow writer or an editor to copyedit your work; and request a developmental edit if you feel that it’s warranted.

ただし固有名詞(例:Google)や引用などが続く場合は小文字にする必要はありません。


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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(14):UI要素の書き方5 ― 操作を表す動詞

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

操作を表す動詞

URL: https://developers.google.com/style/ui-elements#verbs (2020-12-29閲覧)

UI上での操作を表す際に用いる動詞がいくつかあります。操作説明を読んだり書いたりするのに覚えておきたい言葉ばかりです。なおサンプル英文はGoogleのものです。

Click(クリックする)

clickは「他動詞」として用いることとされています。つまり、以下の例のように前置詞onは入れず、clickの直後に目的語(「OK」というラベル)を置きます。

  • ✕ Click on OK.
  • ◯ Click OK.

ただし、背面にあるウィンドウをクリックして前面に表示するような場合は前置詞inを入れて「Click in the window.」としてよいとされています。具体的な何かをクリックする(他動詞)というより、ウィンドウ枠内で単にクリック操作をする(自動詞)という捉え方のためでしょう。

また右クリック、左クリック、ダブル・クリックという動詞は、それぞれ「right-click」、「left-click」、「double-click」とハイフンでつなぐ形とします。

Drag(ドラッグする)

動詞dragを用いる際に「click and drag」や「drag and drop」という表現は使わないとしています。これは、dragという動詞自体に「マウス・ボタンをクリックしたまま移動させ、目的地でボタンを離す」という一連の動作が含意されており、「click and drag」や「drag and drop」では冗長だからだと思われます。

  • ◯ Drag the USER to the Authorized box.

ただし形容詞としての「drag-and-drop」は可です。

Enter、Type(入力する)

テキストの入力を示す際はどちらの動詞も使えます。

  • ◯ In the Owner box, enter your name.
  • ◯ In the Size box, type or select a font size.

特にtypeは名詞の「型」や「タイプ」と読み間違えることが多いので、注意しましょう。

Hold the pointer over(ポインターを〜の上に置く)

少しの間、マウスのポインターをアイコンなどの上に置いておく動作は、一般的に「ホバー」(hover)と呼ばれます。しかしGoogleスタイルガイドでは、このhoverではなく「hold the pointer over」という表現を使うとしています。理由は不明ですが、より具体的あるいは説明的だからかもしれません。

  • ◯ In the Admin menu, hold the pointer over File, and then click New.

Press(押す)

キーボードのキー(やその組み合わせ)を押す動作で使います。

  • ◯ Press Control+C (or Command+C on Mac).

上記例で、キー名はUIラベルと違ってボールド表記にしていない点に注意してください。キー名には等幅フォントを使い、HTMLでは<kbd>要素で囲みます(参考)。

Select(選択する)

メニューで項目を選ぶ際に使います。状況によっては「click」や「check」(チェックボックスの選択)という動詞の代わりに「select」を使ってもよいとしています。

  • ◯ Select File > New.
  • ◯ In the Font drop-down list, select Roboto.

なお同義語に「choose」がありますが、chooseはより日常語に近いと言えます。selectは特にメニューから選ぶ際に用いられます。


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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(13):UI要素の書き方4 ― キー操作

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

キー操作

URL: https://developers.google.com/style/ui-elements#keyboard (2020-11-27閲覧)

開発者であれば、ちょっとした操作説明を英語で書く機会があります。操作説明におけるUI要素の書き方の第4回目で、今回はキーボードのキー操作を取り上げます(第1回2回3回)。なお英語例文はGoogleのものです。

等幅フォントを使う

ボタンなどのUI要素はボールドで囲む(例: Click Next.)のが基本です。

一方でキーボードのキーを表す場合は、等幅フォント(monospace)を使うとしています。HTMLの場合は「<kbd>」要素を使うことで等幅での表示が可能です。

  • ◯ Press Control+C.
    • 上記のHTML:Press <kbd>Control+C</kbd>.

キー名のみか、theとkeyを付けるか

キー名(たとえば「Esc」)を指す際は、以下のどちらの表記も使えます。

  • ◯ Press Esc.
  • ◯ Press the Esc key.

つまりキー名だけ、または、theとkeyも付けるか、という書き方です。

なお、なぜtheとkeyという形になるのかという理由は、記事「UI要素の書き方1」の「theを付けるか付けないか」セクションで説明しています。

キーの組み合わせ

複数のキーを一緒に押すときは「修飾キー+キー」で表記します。

  • ◯ Press Control+V.

さらにシフト・キーも押す場合も「+」で書き加えます。

  • ◯ Press Control+Shift+?.

もしキーが「.」や「+」などで読者が混乱しそうであればスペルアウト(例:period、plus)するとしています。

【補足】キーの英語表記サンプル

「Chrome DevTools」のキーボード・ショートカットがこちらのページにまとめられています。英語で書く際に悩みそうな表記をいくつかサンプルとして転載します。

英語表記サンプル説明
Control+Shift+Cコントロールとシフト
Command+Option+Jコマンドとオプション
Function+F1ファンクション
Escapeエスケープ。上の例では「Esc」とも
ReturnEnterReturnはMac、EnterはWindows
Control+.ピリオド。スペルアウトはされていない
UpDownLeftRight Arrow
(例:Press Shift+Up Arrow.)
上下左右の矢印
取得元: https://developers.google.com/web/tools/chrome-devtools/shortcuts (2020-11-27閲覧)

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(12):UI要素の書き方3 ― チェックボックスなど

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

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

テキスト・ボックス、チェックボックス、ラジオボタンなど

URL:https://developers.google.com/style/ui-elements#ui-terms (2020-10-29閲覧)

開発者であれば、ちょっとした操作説明を英語で書く機会があります。今回は、操作説明におけるUI要素の書き方の3回目です(第1回2回)。なお英語例文はGoogleのものです。

テキスト・ボックス(text box)

ユーザーが入力できるUIです。それ自体は「text box」ですが、例文のように「the ◯◯ box」と表現するとしています。動詞は「enter」(入力する)がよく用いられます。

  • ◯: In the Owner box, enter your name.

リスト・ボックス(list box)

項目をリストで表示するUIです。ドロップダウン式の場合、「the ◯◯ drop-down list」と表現するとしています。この場合の動詞は「select」(選択する)です。

  • ◯: In the Item drop-down list, select Desktop.

コンボ・ボックス(combo box)

テキスト・ボックスとリスト・ボックスが組み合わさったUIです。「the ◯◯ box」と表現します。動詞は「type or select」または「enter」を使うとしています。なおtypeは「(キーボードで)入力する」という意味です。名詞の「型」や「タイプ」ではないので注意しましょう。

  • ◯:  In the Font box, type or select the font you want to use.

チェックボックス(checkbox)

チェックボックスは「checkbox」と1語であり、「check box」と2語ではない点に注意してください。

また、チェックボックスにチェックを入れる(オンにする)と表現する場合、動詞は「check」よりも「select」を使うとしています。またオフにするのは「clear」という動詞を使います。

  • ◯: Select the Automatically check for updates checkbox.
  • ◯: Clear the Bookmarks checkbox.

なお、オフでは「deselect」や「uncheck」という動詞も候補になりますが、これらも使わないとしています。

ラジオボタン(radio button)

ラジオボタンの選択肢を表現する場合、例文のようにラベルをそのまま書くとしています(「the ◯◯ radio button」のようにはしない)。

  • ◯: Click Do not remember passwords.

トグル(toggle)

オンとオフを切り替えるUIです。toggleという英単語は名詞としてUI自体を指しますが、「切り替える」という動詞でもあります。以下の1つ目の例文が動詞、2つ目が名詞です。

  • ◯: You can toggle Magic Mode in the Settings window.
  • ◯: To enable, click the Wi-Fi toggle.

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(11):UI要素の書き方2 ― ウィンドウなど

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

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

ウィンドウ、メニュー・バーなど

URL:https://developers.google.com/style/ui-elements#ui-terms (2020-09-28閲覧)

開発者であれば、ちょっとした操作説明を英語で書く機会があります。今回は、操作説明におけるUI要素の書き方の2回目です(第1回はこちら)。なお英語例文はGoogleのものです。

ウィンドウなどの画面区画

画面の区画を指す英単語がいくつかあります。以下のように使い分けます。

window:あるアプリ全体のウィンドウに加え、そのアプリの一部になっているツールなどのウィンドウを指すのにも使う

page:主にウェブ・ページを指すのに使う

dialog:メインのアプリケーション・ウィンドウの手前に表示され、独立した小さなウィンドウを指すのに使う

  • ✕:In the Welcome pop-up window, click OK.
  • ◯:In the Welcome dialog, click OK.

pane:ウィンドウの中にある区画を指すのに使う。発音は「ペイン」で、一般英語としては「窓のガラス1枚」を指す(「田」の形の窓なら4枚のペインがある)。

前置詞は基本的に「in」ですが、pageの場合だけは「on」を使います。

  • ◯:In the Task window, click Start.
  • ◯:On the Create an instance page, click Add.

また「In 〜」のように、操作の場所を先に書くようにしましょう。そうすると、読者の視線の移動に合います。

メニュー・バー

ウィンドウや画面の最上部にあるのがメニュー・バー(menu bar)です。

メニュー・バーでは「ファイル」→「保存」のように、下位項目を連続して選択する操作がよくあります。この連続操作では「>」を使って示します。

  • ◯:Select View > Tools > Developer Tools.

Googleのスタイルガイドでは、この「>」を使った表記方法はメニュー・バーのみに使うとしています。また「>」自体もUIと同じくボールドとしています。

ボタンとアイコン

ボタンを指し示す際は、ボタンのラベルを使います。

  • ✕:Click the “OK” button.
  • ◯:Click OK.

ボタンがアイコンの場合、ツールチップに表示される名前(マウス・カーソルを置いたときにポップアップで出る名前)を書き、その直後にアイコン画像を表示します。

  • ✕:Click the + icon.
  • ◯:Click Add +. (※「+」は画像)

また、UI要素に三点リーダー(エリプシス)がある場合は含めません。

  • ✕:Click Browse ….
  • ◯:Click Browse.

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

英文スタイルガイド解説(10):UI要素の書き方1 ― ボールドなど

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

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

ボールドで囲む、theを付けるか

URL:https://developers.google.com/style/ui-elements#formatting (2020-08-26閲覧)

開発者であれば、ちょっとした操作説明を英語で書く機会はあります。そのときボタン名やメニュー名などのUI要素をどう扱うか悩むはずです。今回から複数回にわたって、操作説明におけるUI要素の書き方を解説します。なお英語例文はGoogleのものです。

ボールドで囲む

日本語ではUI要素を鍵かっこで囲ったり(例:「編集」を選択)、角かっこで囲ったり(例:[履歴] をクリック)することが多いかと思います。英語で書くときは、UI要素をボールドで書くようにします。

  • ✕: In the New Project window, select “New Activity”, and then click the “Next” button.
    • → ダブルクォーテーション(” “)は使わない
  • ◯: In the New Project window, select the New Activity checkbox, and then click Next.

theを付けるか付けないか

上記の例では「In the New Project window」と定冠詞theが付いていたり、「click Next」と付いていなかったりします。冠詞がない日本語の母語話者にとっては対応に悩む部分です。

例文をよく見ると、theがあるのは「the New Project window」のwindowや「the New Activity checkbox」のcheckboxのような普通名詞がUI要素の後に置かれるときです。他方、UI要素そのままの場合(例:click Next)にはtheがありません。これは文法的に言うと、普通名詞ではなく「固有名詞」のように扱われているためだと思われます。

つまりルールとしては、
・UI要素の後ろにwindowなど普通名詞が付く → theは必要
・UI要素がそのまま → theは不要
となります。

実際、別の例文を見ても上記の形となっています。

  • ◯: In the File menu, click Tools.
  • ◯: In the MyApp window, click Edit.

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter

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


[筆者について]
西野竜太郎。IT分野の英語翻訳者/リンギスト。訳書に「血と汗とピクセル」、著書に「アプリケーションをつくる英語」(第4回ブクログ大賞)、「ITエンジニアのための英語リーディング」、「ソフトウェア・グローバリゼーション入門」、「アプリ翻訳実践入門」など。ブログTwitter