StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Google Documentation Guide

Browse Source 
Includes Markdown Style Guide
See docguide/README.md
This commit is contained in:
Nodir Turakulov 2015-08-31 10:46:32 -07:00
parent 43d738ab8b
commit edccafae5a
6 changed files with 686 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docguide/README.md Normal file
View File

@ -0,0 +1,10 @@
# Google documentation guide
* [Markdown styleguide](style.md)
* [Best practices](best_practices.md)
* [README files](READMEs.md)
* [Philosophy](philosophy.md)
## See also
* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.

69
docguide/READMEs.md Normal file
View File

@ -0,0 +1,69 @@
# README.md files
About README.md files.
1. [Overview](#overview)
1. [Guidelines](#guidelines)
1. [Filename](#filename)
1. [Contents](#contents)
1. [Example](#example)
## Overview
`README.md` files are Markdown files that describe a directory.
GitHub and Gitiles renders it when you browse the directory.
For example, the file /README.md is rendered when you view the contents of the
containing directory:
https://github.com/google/styleguide/tree/gh-pages
Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
index:
https://gerrit.googlesource.com/gitiles/
## Guidelines
**`README.md` files are intended to provide orientation for engineers browsing
your code, especially first-time users.** The `README.md` is likely the first
file a reader encounters when they browse a directory that
contains your code. In this way, it acts as a landing page for the directory.
We recommend that top-level directories for your code have an up-to-date
`README.md` file. This is especially important for package directories that
provide interfaces for other teams.
### Filename
Use `README.md`.
Files named `README` are not displayed in the directory view in Gitiles.
### Contents
At minimum, every package-level `README.md` should include or point to the
following information:
1. **What** is in this package/library and what's it used for.
2. **Who** to contact.
3. **Status**: whether this package/library is deprecated, or not for general
release, etc.
4. **More info**: where to go for more detailed documentation, such as:
* An overview.md file for more detailed conceptual information.
* Any API documentation for using this package/library.
## Example
```markdown
# APIs
This is the top-level directory for all externally-visible APIs, plus some
private APIs under `internal/` directories.
See [API Style Guide](docs/apistyle.md) for more information.
*TL;DR*: API definitions and configurations should be defined in `.proto` files,
checked into `apis/`.
...
```

1
docguide/VERSION Normal file
View File

@ -0,0 +1 @@
1.0

115
docguide/best_practices.md Normal file
View File

@ -0,0 +1,115 @@
# Documentation Best Practices
"Say what you mean, simply and directly." - [Brian Kernighan]
(http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
Contents:
1. [Minimum viable documentation](#minimum-viable-documentation)
1. [Update docs with code](#update-docs-with-code)
1. [Delete dead documentation](#delete-dead-documentation)
1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
## Minimum viable documentation
A small set of fresh and accurate docs are better than a sprawling, loose
assembly of "documentation" in various states of disrepair.
Write short and useful documents. Cut out everything unnecessary, while also
making a habit of continually massaging and improving every doc to suit your
changing needs. **Docs work best when they are alive but frequently trimmed,
like a bonsai tree**.
This guide encourages engineers to take ownership of their docs and keep
them up to date with the same zeal we keep our tests in good order. Strive for
this.
* Identify what you really need: release docs, API docs, testing guidelines.
* Delete cruft frequently and in small batches.
## Update docs with code
**Change your documentation in the same CL as the code change**. This keeps your
docs fresh, and is also a good place to explain to your reviewer what you're
doing.
A good reviewer can at least insist that docstrings, header files, README.md
files, and any other docs get updated alongside the CL.
## Delete dead documentation
Dead docs are bad. They misinform, they slow down, they incite despair in
engineers and laziness in team leads. They set a precedent for leaving behind
messes in a code base. If your home is clean, most guests will be clean without
being asked.
Just like any big cleaning project, **it's easy to be overwhelmed**. If your
docs are in bad shape:
* Take it slow, doc health is a gradual accumulation.
* First delete what you're certain is wrong, ignore what's unclear.
* Get your whole team involved. Devote time to quickly scan every doc and make
a simple decision: Keep or delete?
* Default to delete or leave behind if migrating. Stragglers can always be
recovered.
* Iterate.
## Prefer the good over the perfect
Your documentation should be as good as possible within a reasonable time frame.
The standards for an documentation review are different from the
standards for code reviews. Reviewers can and should ask for improvements, but
in general, the author should always be able to invoke the "Good Over Perfect
Rule". It's preferable to allow authors to quickly submit changes that improve
the document, instead of forcing rounds of review until it's "perfect". Docs are
never perfect, and tend to gradually improve as the team learns what they really
need to write down.
## Documentation is the story of your code
Writing excellent code doesn't end when your code compiles or even if your
test coverage reaches 100%. It's easy to write something a computer understands,
it's much harder to write something both a human and a computer understand. Your
mission as a Code Health-conscious engineer is to **write for humans first,
computers second.** Documentation is an important part of this skill.
There's a spectrum of engineering documentation that ranges from terse comments
to detailed prose:
1. **Inline comments**: The primary purpose of inline comments is to provide
information that the code itself cannot contain, such as why the code is
there.
2. **Method and class comments**:
* **Method API documentation**: The header / Javadoc / docstring
comments that say what methods do and how to use them. This
documentation is **the contract of how your code must behave**. The
intended audience is future programmers who will use and modify your
code.
It is often reasonable to say that any behavior documented here should
have a test verifying it. This documentation details what arguments the
method takes, what it returns, any "gotchas" or restrictions, and what
exceptions it can throw or errors it can return. It does not usually
explain why code behaves a particular way unless that's relevant to a
developer's understanding of how to use the method. "Why" explanations
are for inline comments. Think in practical terms when writing method
documentation: "This is a hammer. You use it to pound nails."
* **Class / Module API documentation**: The header / Javadoc / docstring
comments for a class or a whole file. This documentation gives a brief
overview of what the class / file does and often gives a few short
examples of how you might use the class / file.
Examples are particularly relevant when there's several distinct ways to
use the class (some advanced, some simple). Always list the simplest
use case first.
3. **README.md**: A good README.md orients the new user to the directory and
points to more detailed explanation and user guides:
* What is this directory intended to hold?
* Which files should the developer look at first? Are some files an API?
* Who maintains this directory and where I can learn more?
See the [README.md guidelines](READMEs.md).

71
docguide/philosophy.md Normal file
View File

@ -0,0 +1,71 @@
# Philosophy
埏埴以為器，當其無，有器之用.
*Clay becomes pottery through craft, but it's the emptiness that makes a pot
useful.*
\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
Contents:
1. [Radical simplicity](#radical-simplicity)
1. [Readable source text](#readable-source-text)
1. [Minimum viable documentation](#minimum-viable-documentation)
1. [Better is better than perfect](#better-is-better-than-perfect)
## Radical simplicity
* **Scalability and interoperability** are more important than a menagerie of
unessential features. Scale comes from simplicity, speed, and ease.
Interoperability comes from unadorned, digestable content.
* **Fewer distractions** make for better writing and more productive reading.
* **New features should never interfere with the simplest use case** and should
remain invisible to users who don't need them.
* **This guide is designed for the average engineer** -- the busy,
just-want-to-go-back-to-coding engineer. Large and complex documentation is
possible but not the primary focus.
* **Minimizing context switching makes people happier.** Engineers should be
able to interact with documentation using the same tools they use to read and
write code.
## Readable source text
* **Plain text not only suffices, it is superior**. Markdown itself is not
essential to this formula, but it is the best and most widely supported
solution right now. HTML is generally not encouraged.
* **Content and presentation should not mingle**. It should always be possible
to ditch the renderer and read the essential information at source. Users
should never have to touch the presentation layer if they don't want to.
* **Portability and future-proofing leave room for the unimagined integrations
to come**, and are best achieved by keeping the source as human-readable as
possible.
* **Static content is better than dynamic**, because content should not depend
on the features of any one server. However, **fresh is better than stale**. We
strive to balance these needs.
## Minimum viable documentation
* **Docs thrive when they're treated like tests**: a necessary chore one learns
to savor because it rewards over time.
See [Best Practices](best_practices.md).
* **Brief and utilitarian is better than long and exhaustive**. The vast
majority of users need only a small fraction of the author's total knowledge,
but they need it quickly and often.
## Better is better than perfect
* **Incremental improvement is better than prolonged debate**. Patience and
tolerance of imperfection allow projects to evolve organically.
* **Don't lick the cookie, pass the plate**. We're drowning in potentially
impactful projects. Choose only those you can really handle and release those
you can't.

420
docguide/style.md Normal file
View File

@ -0,0 +1,420 @@
# Markdown style guide
Much of what makes Markdown great is the ability to write plain text, and get
great formatted output as a result. To keep the slate clean for the next author,
your Markdown should be simple and consistent with the whole corpus wherever
possible.
We seek to balance three goals:
1. *Source text is readable and portable.*
2. *Markdown files are maintainable over time and across teams.*
3. *The syntax is simple and easy to remember.*
Contents:
1. [Document layout](#document-layout)
1. [Character line limit](#character-line-limit)
1. [Trailing whitespace](#trailing-whitespace)
1. [Headings](#headings)
1. [ATX-style headings](#atx-style-headings)
1. [Add spacing to headings](#add-spacing-to-headings)
1. [Lists](#lists)
1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
1. [Nested list spacing](#nested-list-spacing)
1. [Code](#code)
1. [Inline](#inline)
1. [Codeblocks](#codeblocks)
1. [Declare the language](#declare-the-language)
1. [Escape newlines](#escape-newlines)
1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
1. [Links](#links)
1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
1. [Images](#images)
1. [Prefer lists to tables](#prefer-lists-to-tables)
1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
## Document layout
In general, most documents benefit from some variation of the following layout:
```markdown
# Document Title
Short introduction.
[TOC]
## Topic
Content.
## See also
* https://link-to-more-info
```
1. `# Document Title`: The first heading should be a level one heading, and
should ideally be the same or nearly the same as the filename. The first
level one heading is used as the page `<title>`.
1. `author`: *Optional*. If you'd like to claim ownership of the document or
if you are very proud of it, add yourself under the title. However,
revision history generally suffices.
1. `Short introduction.` 1-3 sentences providing a high-level overview of the
topic. Imagine yourself as a complete newbie, who landed on your "Extending
Foo" doc and needs to know the most basic assumptions you take for granted.
"What is Foo? Why would I extend it?"
1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
put `[TOC]` after the short introduction. See
[`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
1. `## Topic`: The rest of your headings should start from level 2.
1. `## See also`: Put miscellaneous links at the bottom for the user who wants
to know more or didn't find what she needed.
## Character line limit
Obey the character line limit wherever possible. Long URLs and tables are the
usual suspects when breaking the rule. (Headings also can't be wrapped, but we
encourage keeping them short.) Otherwise, wrap your text:
```markdown
Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
hendrerit, id nobis saperet fuisset ius.
* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
```
Often, inserting a newline before a long link preserves readability while
minimizing the overflow:
```markdown
Lorem ipsum dolor sit amet. See the
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
for details.
```
## Trailing whitespace
Don't use trailing whitespace, use a trailing backslash.
The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
that two spaces at the end of a line should insert a `<br />` tag. However, many
directories have a trailing whitespace presubmit check in place, and many IDEs
will clean it up anyway.
Best practice is to avoid the need for a `<br />` altogether. Markdown creates
paragraph tags for you simply with newlines: get used to that.
## Headings
### ATX-style headings
```markdown
## Heading 2
```
Headings with `=` or `-` underlines can be annoying to maintain and don't fit
with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or
H2?
```markdown
Heading - do you remember what level? DO NOT DO THIS.
---------
```
### Add spacing to headings
Prefer spacing after `#` and newlines before and after:
```markdown
...text before.
# Heading 1
Text after...
```
Lack of spacing makes it a little harder to read in source:
```markdown
...text before.
#Heading 1
Text after... DO NOT DO THIS.
```
## Lists
### Use lazy numbering for long lists
Markdown is smart enough to let the resulting HTML render your numbered lists
correctly. For longer lists that may change, especially long nested lists, use
"lazy" numbering:
```markdown
1. Foo.
1. Bar.
1. Foofoo.
1. Barbar.
1. Baz.
```
However, if the list is small and you don't anticipate changing it, prefer fully
numbered lists, because it's nicer to read in source:
```markdown
1. Foo.
2. Bar.
3. Baz.
```
### Nested list spacing
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
```markdown
1. 2 spaces after a numbered list.
4 space indent for wrapped text.
2. 2 spaces again.
* 3 spaces after a bullet.
4 space indent for wrapped text.
1. 2 spaces after a numbered list.
8 space indent for the wrapped text of a nested list.
2. Looks nice, don't it?
* 3 spaces after a bullet.
```
The following works, but it's very messy:
```markdown
* One space,
with no indent for wrapped text.
1. Irregular nesting... DO NOT DO THIS.
```
Even when there's no nesting, using the 4 space indent makes layout consistent
for wrapped text:
```markdown
* Foo,
wrapped.
1. 2 spaces
and 4 space indenting.
2. 2 spaces again.
```
However, when lists are small, not nested, and a single line, one space can
suffice for both kinds of lists:
```markdown
* Foo
* Bar
* Baz.
1. Foo.
2. Bar.
```
## Code
### Inline
&#96;Backticks&#96; designate `inline code`, and will render all wrapped content
literally. Use them for short code quotations and field names:
```markdown
You'll want to run `really_cool_script.sh arg`.
Pay attention to the `foo_bar_whammy` field in that table.
```
Use inline code when referring to file types in an abstract sense, rather than a
specific file:
```markdown
Be sure to update your `README.md`!
```
Backticks are the most common approach for "escaping" Markdown metacharacters;
in most situations where escaping would be needed, code font just makes sense
anyway.
### Codeblocks
For code quotations longer than a single line, use a codeblock:
<pre>
```python
def Foo(self, bar):
self.bar = bar
```
</pre>
#### Declare the language
It is best practice to explicitly declare the language, so that neither the
syntax highlighter nor the next editor must guess.
#### Indented codeblocks are sometimes cleaner
Four-space indenting is also interpreted as a codeblock. These can look
cleaner and be easier to read in source, but there is no way to specify the
language. We encourage their use when writing many short snippets:
```markdown
You'll need to run:
bazel run :thing -- --foo
And then:
bazel run :another_thing -- --bar
And again:
bazel run :yet_again -- --baz
```
#### Escape newlines
Because most commandline snippets are intended to be copied and pasted directly
into a terminal, it's best practice to escape any newlines. Use a single
backslash at the end of the line:
<pre>
```shell
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
```
</pre>
#### Nest codeblocks within lists
If you need a codeblock within a list, make sure to indent it so as to not break
the list:
```markdown
* Bullet.
```c++
int foo;
```
* Next bullet.
```
You can also create a nested code block with 4 spaces. Simply indent 4
additional spaces from the list indentation:
```markdown
* Bullet.
int foo;
* Next bullet.
```
## Links
Long links make source Markdown difficult to read and break the 80 character
wrapping. **Wherever possible, shorten your links**.
### Use informative Markdown link titles
Markdown link syntax allows you to set a link title, just as HTML does. Use it
wisely.
Titling your links as "link" or "here" tells the reader precisely nothing when
quickly scanning your doc and is a waste of space:
```markdown
See the syntax guide for more info: [link](syntax_guide.md).
Or, check out the style guide [here](style_guide.md).
DO NOT DO THIS.
```
Instead, write the sentence naturally, then go back and wrap the most
appropriate phrase with the link:
```markdown
See the [syntax guide](syntax_guide.md) for more info.
Or, check out the [style guide](style_guide.md).
```
## Images
Use images sparingly, and prefer simple screenshots. This guide is designed
around the idea that plain text gets users down to the business of communication
faster with less reader distraction and author procrastination. However, it's
sometimes very helpful to show what you mean.
See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
## Prefer lists to tables
Any tables in your Markdown should be small. Complex, large tables are difficult
to read in source and most importantly, **a pain to modify later**.
```markdown
Fruit | Attribute | Notes
--- | --- | --- | ---
Apple | [Juicy](http://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
DO NOT DO THIS
```
[Lists](#lists) and subheadings usually suffice to present the same information
in a slightly less compact, though much more edit-friendly way:
```markdown
## Fruits
### Apple
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet
Apples keep doctors away.
### Banana
* [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet
Contrary to popular belief, most apes prefer mangoes.
```
However, there are times when a small table is called for:
```markdown
Transport | Favored by | Advantages
--- | --- | ---
Swallow | Coconuts | Otherwise unladen
Bicycle | Miss Gulch | Weatherproof
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
```
## Strongly prefer Markdown to HTML
Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
If you can't seem to accomplish what you want, reconsider whether you really
need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
all needs already.
Every bit of HTML or Javascript hacking reduces the readability and portability.
This in turn limits the usefulness of integrations with
other tools, which may either present the source as plain text or render it. See
[Philosophy](philosophy.md).
Gitiles does not render HTML.