Google Developer Documentation Style Guide自分用まとめ

More than 1 year has passed since last update.

https://developers.google.com/style/

から自分にとって有用そうな部分だけを抜粋しておく。


手順は1. 2. a. b. i. ii.

1. First, do foo, as follows:

a. Do the first part of foo.
b. Do the second part of foo. There is no third part.
i. Do the first sub-part of foo part two.
ii. Do the second sub-part of foo part two.
2. Next, do bar.

https://developers.google.com/style/procedures


メニューなどの操作順番を表すには「>」(不等号)を使う

File > New > Document

https://developers.google.com/style/procedures


コマンドと出力の書き方

次のコードをターミナルに入力します:

$ adb devices

以下が出力されます:

List of devices attached

emulator-5554 device
emulator-5556 device


  • プロンプトを表す「$」をつける

  • 他のマシンにsshしたときなどはプロンプトを変えても良い

  • 入力と出力は囲みを分ける

実際の値で置き換えるべきプレースホルダは<var>タグで囲む。すると見た目はイタリックで文字色がピンクになる。

OK: cp from to

NG: cp <from> <to>

NG: cp {from} {to}

https://developers.google.com/style/code-syntax


ユーザーが入力する文字列は<kbd>タグで囲む

https://developers.google.com/style/code-in-text


<code>タグの使い方

以下のものは<code>タグで囲む


  • 言語のキーワード

  • クラス名

  • メソッド名、関数名

  • XMLやHTMLの要素名

  • 属性名と値

  • ファイル名やパス

  • 属性や値の取りうる定数値

  • 名前空間のエイリアス

  • HTTPの動詞

  • HTTPステータスコード

  • HTTPのcontent-typeの値

  • クエリーパラメータ名とその値

  • コマンドラインユーティリティ名

以下のものは普通のフォントで表記する


  • URL

  • メールアドレス

  • 見出し

https://developers.google.com/style/code-in-text


メソッド名の書き方

OK: メタデータを取得するにはget()メソッドを呼びます。

クラス名や引数名を含めても良い:

OK: TextView.setText()

OK: setText(CharSequence, TextView.BufferType)


注意書きはNote, Caution, Warning, Success

ちなみにMicrosoftはNote, Tip, Important, Cautionを使っている。

https://developers.google.com/style/notices


見出しの最初の文字は大文字にする

https://developers.google.com/style/capitalization


数字と単位の間にはスペースを入れる

NG: 64GB

OK: 64 GB

https://developers.google.com/style/units-of-measure