Googleスタイルガイド

2026年9月23日

はじめに

この文書は、Googleドキュメンテーションスタイルガイドの入門書である。内容はGoogle documentation guideに基づいている。

哲学

徹底したシンプルさ（Radical simplicity）

  • スケーラビリティと相互運用性は、不要な機能の寄せ集めより重要である。スケールはシンプルさ・速さ・手軽さから生まれ、相互運用性は飾り気のない、消化しやすい内容から生まれる。
  • 不要な要素が少ないほど、執筆は良くなり、読書は生産的になる。
  • 新しい機能は、最もシンプルなユースケースに絶対に干渉してはならない。必要としないユーザーには見えないままであるべきだ。
  • ドキュメントは、平均的なエンジニアのために設計されている。つまり、忙しくて、コードに戻りたいだけのエンジニアだ。大規模で複雑なドキュメントも可能だが、それは主眼ではない。
  • コンテキストスイッチを最小化すると、人は幸せになる。エンジニアは、コードを読んだり書いたりするのと同じツールで、ドキュメントも扱えなければならない。

読みやすいソーステキスト（Readable source text）

  • プレーンテキストは、十分であり、しかも優れている。Markdown自体は必須ではなく、ただ現在最良で最も広くサポートされている解決策である。HTMLは一般的に推奨されない。
  • 内容と表現は混在してはならない。レンダラーを捨てても、ソースから本質的な情報を読めなければならないはずだ。
  • ポータビリティと将来性は、まだ想像されていない将来の統合の余地を残す。これはソースをできるだけ人間が読める状態に保つことで、最もよく実現される。
  • 静的な内容は動的内容より良い。内容は、特定のサーバーの機能に依存すべきではないからだ。ただし、新鮮さは陳腐化より良い。これらのニーズは互いにバランスさせる。

最小限の実用ドキュメント（Minimum viable documentation）

  • ドキュメントは、テストのように扱うと健全に育つ。時間とともに報われることから、必要な作業として味わえるようになる。
  • 短くて実用的であることが、長く網羅的であることより良い。大半のユーザーは著者の総知識のほんの一部しか必要としないが、それを早く、頻繁に必要とする。

最善より良い（Better is better than best）

  • 漸進的な改善が、長期にわたる議論より良い。不完全さへの忍耐が、プロジェクトを有機的に進化させる。
  • アイデアは安価で、インパクトがありそうなプロジェクトは山ほどある。本当に引き受けられるものだけを選び、あとは手放す。

ベストプラクティス

最小限の実用ドキュメント（Minimum viable documentation）

  • 新鮮で正確な小さなドキュメントのセットが、壊れかけの「ドキュメント」の大量寄せ集めより良い。
  • 短くて役に立つ文書を書く。古い・誤りのある・重複した情報など、不要なものはすべて削る。ニーズの変化に合わせて、常にドキュメントを整える。
  • ドキュメントは盆栽のように、生きているが頻繁に剪定される状態で最も機能する。
  • Markdownの思想は、自分のドキュメントのオーナーシップを取り、テストを整えるのと同じ熱心さで最新に保つことを奨励する。
  • 本当に必要なものを特定する：リリースドキュメント、APIドキュメント、テスト指針。
  • 不要な残骸を、頻繁に、小刻みに削除する。

ドキュメントをコードと同時に更新する（Update Docs with Code）

  • ドキュメントの変更は、コードの変更と同じCL（Change List、1つの変更＝レビューに回すコミットの束の単位。Pull Requestに相当）で行う。これでドキュメントが新鮮に保たれ、レビュアーに自分が何をしようとしているかを説明する自然な場にもなる。
  • 良いレビュアーは少なくとも、docstring・ヘッダファイル・README.md・その他のドキュメントがCLと同時に更新されることを求める。

死んだドキュメントを削除する（Delete Dead Documentation）

  • 死んだドキュメントは悪である。誤った情報を広め、人を遅くし、エンジニアに絶望と、チームリードに怠慢を抱かせ、コードベースをぐちゃぐちゃにして残す前例を作る。家が清潔であれば、ほとんどの客は頼まれなくても清潔である。
  • 大掃除と同じで、圧倒されやすい。ドキュメントが悪状態なら、次のように進める：
    • ゆっくり進める。ドキュメントの健全さは、少しずつ積み上がるものだ。
    • まず確実に誤っているものを削除する。曖昧なものは無視する。
    • チーム全員を巻き込む。すべてのドキュメントを素早く走査し、単純な判断を下す：残すか、削除するか。
    • 迷ったら削除するのがデフォルト。移行中ならその場に置いていく。取り残されたものは後で必ず復元できる。
    • 繰り返す。

完全より良いを優先する（Prefer the Good Over the Perfect）

  • ドキュメントは芸術である。完璧な文書は存在しない。あるのは、実証された方法と賢明な指針だけだ。

レビューでのベター/ベスト則（Better/Best Rule）

ベター/ベスト則は「better is better than best」、つまり「ベスト（完璧）を待つより、ベター（現状より改善したもの）を優先する」という則である。レビューでは、変更が現状のドキュメントより良くしているなら、それを取り込むべきで、完璧を理由に差し止めたりすべきではない。

  • ドキュメントレビューの基準は、コードレビューの基準と異なる。レビュアーは改善を求めてよいが、著者は常にベター/ベスト則を主張してよい。
  • 素早い反復が味方である。長期的な改善のためには、短期的な改善をしながらでも著者が生産性を保たなければならない。CLごとの基準を下げれば、そうしたCLがより多く生まれる。
  • ドキュメントCLのレビュアーとしては：
    • 合理的な範囲では、即LGTM（Looks Good To Me、承認OK）にし、コメントは適切に直されることを信頼する。
    • 曖昧なコメントを残すより、代替案を提案する。
    • 大きな変更は、自分でフォローアップCLを立てる。特に「〜もしたほうがよい」系のコメントは避ける。
    • まれに、CLが文書を実際に悪くする場合は差し止める。著者に差し戻しを求めてもよい。
  • ドキュメントの著者としては：
    • 細論に時間を浪費しない。早期に譲り、先に進む。
    • ベター/ベスト則を必要に応じて頻繁に引用する。

ドキュメントはコードの物語（Documentation is the Story of Your Code）

  • 素晴らしいコードを書くことは、コンパイルが通ったとき、いやテストカバレッジが100%に達したときでさえ、終わらない。コンピュータに理解させる何かを書くのは簡単だ。人間とコンピュータの両方に理解させる何かを書くのは、はるかに難しい。コードヘルスを意識するエンジニアとしての使命は、まず人間に、次にコンピュータに向けて書くことだ。ドキュメントはこのスキルの重要な部分である。
  • エンジニアリングドキュメントは、簡潔なものから詳細なものまでのスペクトラムを持つ：
    1. 意味のある名前。良い命名により、コードがコメントやドキュメントに回されるはずの情報を持てるようになる。ローカル変数からクラス、ファイル、ディレクトリまで、すべてのレベルで。
    2. インラインコメント。主な役割は、コード自体が含めない情報を提供することだ。例えば、そのコードがなぜそこにあるかなど。
    3. メソッド・クラスAPIドキュメント。
      • メソッドAPIドキュメント（ヘッダ/Javadoc/docstring）は、メソッドが何をし、どう使うかを述べる。これはコードがどう振る舞わなければならないかの契約であり、自分のコードを使う・修正する未来のエンジニアに向けて書かれる。ここに書かれた振る舞いは、検証するテストがあるべきだ。引数、戻り値、注意点や制限、スローされうる例外や返されるエラーを詳述する。「なぜ」の説明はインラインコメントに属する。実用的に考える：「これはハンマーだ。釘を打つのに使う」。
      • クラス/モジュールAPIドキュメントは、クラスやファイルが何をするかの短い概要を与え、使い方への短い例をいくつか示すことが多い。使い方が複数ある（いくつか上級、いくつか簡単）場合は、例が特に重要になる。常に最もシンプルなユースケースを最初に書く。
    4. README.md。良いREADMEは、新しいユーザーがこのディレクトリで何を見ればいいかを示し、より詳しい説明やユーザーガイドへの道しるべとなる：このディレクトリは何を置く場所か、まずどのファイルを見るべきか、誰が管理しているか。
    5. docsディレクトリ。良いdocsディレクトリの中身は、関連するAPI・ライブラリ・ツールをどのように始め、テストをどのように走り、出力をどのようにデバッグし、バイナリをどのようにリリースするかを説明する。
    6. 設計ドキュメントとPRD（Product Requirements Document、製品要件定義書）。良い設計ドキュメントやPRDは、フィードバックを集めるために提案された実装を詳しく論じる。コードが実装された後は、それらの決定のアーカイブとして機能すべきで、半分正しいドキュメント（それはよく誤用される）としてではない。
    7. その他の外部ドキュメント。一部のチームは、Google Sites・Drive・wikiなど、コードから離れた場所にドキュメントを置く。そうしている場合、プロジェクトディレクトリからその場所を明確に指し示すべきだ。例えば、プロジェクトのREADME.mdからその場所への目立つリンクを張るなど。

重複は悪（Duplication is Evil）

  • 既存のガイドがあるのに、共通の技術やプロセスのガイドを自作するのはやめる。既存のガイドにリンクする。
  • ガイドが存在しない、またはひどく古くなっている場合は、適切なディレクトリに自分の更新を提出するか、パッケージレベルのREADME.mdを作成する。
  • オーナーシップを取り、遠慮しない。他のチームは普通、自分の貢献を歓迎する。

Markdownスタイルガイド

Markdownの魅力の多くは、プレーンテキストを書いただけで、うまく整形された出力が得られる点にある。次の著者のために盤面をきれいに保つため、Markdownは可能な限りシンプルで、文書群全体と一貫したものであるべきだ。

以下の規約は、3つの目標のバランスを求めている：

  1. ソーステキストが読みやすく、ポータブルであること。
  2. 文書群が時間とともに、チームをまたいで保守可能であること。
  3. 構文がシンプルで覚えやすいこと。

大文字小文字

  • 製品名・ツール名・バイナリ名は、原文の大文字小文字を保つ。

ドキュメントのレイアウト

ドキュメントには、タイトル、任意の著者、短い導入、[TOC]、H2以降のセクション、See also、というレイアウトが役立つ。

# Document Title

Short introduction.

[TOC]

## Topic

Content.

## See also

* https://link-to-more-info
  • タイトル。最初の見出しはH1であり、理想はファイル名と同一かそれに近いこと。最初のH1がページのタイトルとして使われる。
  • 著者（任意）。ドキュメントの所有権を主張したい場合、タイトル下に自分の名前を書く。通常は改訂履歴で十分だ。
  • 短い導入。1〜3文でトピックの高レベルな概要を与える。何も知らない初心者がこのページにたどり着いた自分を想像する。
  • [TOC]。Gitiles（Google製のGitリポジトリ用ウェブビューア）のように目次をサポートするホスティングを使っている場合、短い導入の後ろに[TOC]を置く。
  • H2セクション。以降の見出しはH2から始める。
  • See also。もっと知りたい人、あるいは探しているものが見つからなかった人のために、雑多なリンクを一番下に置く。

目次（[TOC]）

  • ラップトップで1画面に収まる場合以外は、[TOC]ディレクティブを使う。
  • ディレクティブは、導入の後ろ、最初のH2見出しの前に置く。
  • 位置は、ページを視覚的に見る読者にとってはあまり重要ではない。レンダリングされた目次は、ページの上部に常に現れるからだ。スクリーンリーダーやキーボード操作を使う人にとっては大きく関係する。[TOC]は、ディレクティブを置いた場所に、ちょうどそこへ目次のHTMLをDOMに挿入するからだ。ファイルの一番下に置けば、スクリーンリーダーは文書の最後までたどり着くまで読まない。

1行の文字数制限

  • Markdownの内容は、コードと同じく、80文字の1行制限の慣行に従う。
  • ツール統合：ツールはコードを軸に設計されているため、ドキュメントが似たルールに従うほど、ツールはうまく機能する。例えばCode Searchはソフトラップをしない。
  • 品質：エンジニアがMarkdownを作成・編集するときに、自分の使い慣れたコーディングの習慣を適用するほど、品質は上がる。Markdownは、すでに持っている優れたレビュー文化を活かしている。
  • 例外：リンク、表、見出し、コードブロック。リンクを含む行は、関連する句読点とともに80列を越えてよい。ただしリンクの前後のテキストは折り返す。

行末の空白

  • 行末の空白を使わない。
  • CommonMark仕様は行末の2スペースでハードブレーク（表示で必ず改行する強制改行）を挿入すると定めるが、多くのディレクトリに行末空白を検出するpresubmitチェック（変更を提出する前に自動で走るチェック）があり、多くのIDEが勝手に掃除する。
  • 改行が必要な場合は、行末のバックスラッシュを使う。ただし節制して。
  • 最良の実践は、ハードブレークの必要そのものを避けることだ。2つの改行で段落が生まれる。それに慣れる。

見出し

  • ATXスタイル見出し（#記号）を使う。=や-の下線付き見出しは保守がしにくく、見出し構文の残りにも馴染まない。編集者が問われることになる：---はH1か、H2か？
  • 各見出しに、サブセクションでも、一意で完全に記述的な名前を使う。リンクアンカーは見出しから作られるため、これで自動生成されるアンカーが直感的で明確になる。
  • スペースを入れる：#の後ろに1スペース、見出しの前後に改行。
  • H1見出しは1つだけ、文書のタイトルとして使う。以降の見出しはH2以下にする。
  • タイトルや見出しの大文字小文字は、Google Developer Documentation Style Guideの指針に従う。

リスト

  • 変更がありうる長いリスト、特に長い入れ子リストには、レイジー番号を使う：全項目を1.と書く。Markdownは結果の番号を正しくレンダリングする。
  • リストが小さく、変更しないと予想される場合は、完全に番号をつけたリストを優先する。ソースで読みやすいからだ。
  • リストをネストする場合は、番号付き・箇条書きのどちらも4スペースインデントを使う。折り返した行も4スペースインデント、入れ子内の折り返しは8スペースインデント。
  • ネストがなくても、一貫した4スペースインデントが折り返しテキストのレイアウトをきれいに保つ。
  • リストが小さく、ネストせず、1行ものの場合は、1スペースで十分である。

コード

  • バッククォートはインラインコードを示す。短いコード引用、フィールド名、一般的な意味でのファイルタイプに使う。
  • エスケープにコードスパン（文中に埋め込む短いコード＝インラインコード）を使う：テキストを通常のMarkdownとして処理したくない場合、例えば誤った自動リンクを招く偽のパスや例URLなどは、バッククォートで囲む。
  • 1行より長いコード引用には、フェンス型コードブロックを使う。
    • 言語を明示的に宣言する。シンタックスハイライターも次の編集者も推測しないですむように。
    • インデント型コードブロックよりフェンス型を優先する。インデント型はソースではきれいに映ることもあるが、言語を指定できない（Markdownのいくつかの機能は言語指定子に依存する）、コードブロックの始まりと終わりが曖昧になり、Code Searchでの検索が困難になる。
    • コマンドラインのスニペットの改行は、1つの行末バックスラッシュでエスケープする。そうしたスニペットの多くは、そのままターミナルにコピー＆ペーストされることを想定している。
    • リストの中にコードブロックをネストする場合は、リストを壊さないようインデントする。

リンク

  • 長いリンクはソースのMarkdownを読みづらくし、80文字の折り返しを壊す。可能な限り、リンクを短くする。
  • Markdown内のリンクには、明示的なパスを使う。完全な限定URLまでは必要ない。
  • 相対パスは同一ディレクトリ内ならかなり安全だ。../で他のディレクトリへ伸びるパスは避ける。
  • 情報量の多いリンク文字列を使う。ユーザーは多くの場合、ドキュメントを読まずに走査する。「here」「link」と命名したり、対象URLを重複させたりするリンクは、急いでいる読者に何の情報も与えず、スペースの無駄である。代わりに、文を自然に書き、最も適切な語句を後からリンクで包む。
  • 参照リンクは、リンクの使用とリンクの定義を分離する。次の場合に使う：
    • インラインにすると周囲のテキストの読みやすさを損なう、長いリンクや画像URLの場合。短くてインラインに収まるリンクには使わない。
    • 表の中で、より頻繁に。セルを短く保つために。Markdownはセル内のテキストを複数行に分けられないため、小さい表ほど読みやすい。
    • 同じ先が複数回参照される際の重複を減らすために。
  • 参照リンクの定義は、初回使用の後に行う：初回に使ったセクションの末尾、次の見出しの直前に置く。参照リンクは脚注、現在のセクションは現在のページのように考える。エディタがどこに置くべきか自分なりの考えを持っている場合、それに逆らわない。ツールが常に勝つ。
  • 例外：複数のセクションで使われる定義は、文書末尾に置く。セクションが更新されたり移動したりしたときの宙ぶらりんのリンクを避けるためだ。

画像

  • 画像は控えめに使い、シンプルなスクリーンショットを優先する。
  • 読者に何かを「見せる」方が「説明する」より簡単である場合、画像を使う。UIの操作方法を説明するのは、テキストより画像の方がやりやすいことが多い。
  • 適切なaltテキストを与える。視覚に障害のある読者は画像を見られず、それでも内容を理解する必要がある。

表

  • 素早く走査する必要がある表向きなデータに表を使う。
  • データがリストで簡単に表現できる場合は、表を避ける。リストはMarkdownでは書きやすく読みやすい。
  • データが表向きでないサイン：複数の列が行によって変化しない、またはいくつかのセルが空（分布が悪い）、列に対して行数が少なくどちらかに傾いている（次元の不均衡）、セルに長々とした散文がある。表は一瞥で簡潔な物語を語らなければならない。
  • 2次元にわたる比較的均一なデータ分布がある場合、または異なる属性を持つ並列項目が多い場合、表が最良の選択だ。コンパクトな表は読みやすさを高めることがある。
  • 参照リンクを使い、表のセルを短く、行の長さを管理可能に保つ。

MarkdownをHTMLより強く推奨

  • 可能な限り標準のMarkdown構文を優先し、HTMLハック（Markdown構文ではやりにくいことを、<div> や <span style=...> のような raw HTML タグに逃げ込んで無理やり実現すること）を避ける。
  • 望むことが実現できないようなら、本当にそれが必要か再考する。大きな表を除き、Markdownはすでにほぼすべてのニーズを満たす。
  • HTMLハックの1つひとつが、文書群の読みやすさとポータビリティを損ない、ソースをプレーンテキストとして提示したりレンダリングしたりする他ツールとの統合の有用性を制限する。
  • GitilesはHTMLをレンダリングしない。

READMEの書き方

READMEとは

  • READMEは、ディレクトリの中身の短い要約である。ファイルの内容は、GitHubやGitilesでディレクトリの中身を表示したときに表示される。
  • READMEファイルは、コードをブラウジングする人々、特に初めて使う人のために、重要な情報を与える。

名前と場所

  • READMEファイルの名前はREADME.mdでなければならない。ファイル名は.md拡張子で終わらなければならず、大文字小文字は区別される。
  • 他のMarkdownファイルと異なり、README.mdはドキュメントディレクトリの中に置くべきではない。実際のコードベースのトップレベルディレクトリに置く。
  • コードパッケージのすべてのトップレベルディレクトリに、最新状態のREADME.mdが必要である。特に他のチームに向けてインターフェースを提供するパッケージディレクトリでは重要だ。

READMEに含める内容

  • 最低限、ユーザー向け・チーム向けドキュメントへのリンクを含める。
  • すべてのパッケージレベルのREADME.mdには、次の情報を含めるか、そこに指し示す：
    1. このパッケージ・ライブラリの中身と用途。
    2. 連絡先。
    3. ステータス：非推奨か、一般リリース対象外かなど。
    4. 使い方。サンプルコードや、bazel run/bazel testのコピー可能なコマンドなど。
    5. 関連ドキュメントへのリンク。

参考文献