55
66Contents:
77
8- 1 . [ Minimum viable documentation] ( #minimum-viable-documentation )
9- 1 . [ Update docs with code] ( #update-docs-with-code )
10- 1 . [ Delete dead documentation] ( #delete-dead-documentation )
11- 1 . [ Documentation is the story of your code] ( #documentation-is-the-story-of-your-code )
8+ 1 . [ Minimum Viable Documentation] ( #minimum-viable-documentation )
9+ 1 . [ Update Docs with Code] ( #update-docs-with-code )
10+ 1 . [ Delete Dead Documentation] ( #delete-dead-documentation )
11+ 1 . [ Prefer the Good Over the Perfect] ( #prefer-the-good-over-the-perfect )
12+ 1 . [ Documentation is the Story of Your Code] ( #documentation-is-the-story-of-your-code )
13+ 1 . [ Duplication is Evil] ( #duplication-is-evil )
1214
13- ## Minimum viable documentation
15+ ## Minimum Viable Documentation
1416
15- A small set of fresh and accurate docs are better than a sprawling, loose
16- assembly of "documentation" in various states of disrepair.
17+ A small set of fresh and accurate docs is better than a large assembly of
18+ "documentation" in various states of disrepair.
1719
18- Write short and useful documents. Cut out everything unnecessary, while also
19- making a habit of continually massaging and improving every doc to suit your
20- changing needs. ** Docs work best when they are alive but frequently trimmed,
21- like a bonsai tree** .
20+ Write short and useful documents. Cut out everything unnecessary, including
21+ out-of-date, incorrect, or redundant information. Also make a habit of
22+ continually massaging and improving every doc to suit your changing needs.
23+ ** Docs work best when they are alive but frequently trimmed, like a bonsai
24+ tree** .
2225
23- This guide encourages engineers to take ownership of their docs and keep
24- them up to date with the same zeal we keep our tests in good order. Strive for
25- this.
26+ See also
27+ [ these Agile Documentation best practices] ( https://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm ) .
2628
27- * Identify what you really need: release docs, API docs, testing guidelines.
28- * Delete cruft frequently and in small batches.
29-
30- ## Update docs with code
29+ ## Update Docs with Code
3130
3231** Change your documentation in the same CL as the code change** . This keeps your
3332docs fresh, and is also a good place to explain to your reviewer what you're
3635A good reviewer can at least insist that docstrings, header files, README.md
3736files, and any other docs get updated alongside the CL.
3837
39- ## Delete dead documentation
38+ ## Delete Dead Documentation
4039
4140Dead docs are bad. They misinform, they slow down, they incite despair in
4241engineers and laziness in team leads. They set a precedent for leaving behind
@@ -54,39 +53,37 @@ docs are in bad shape:
5453 recovered.
5554* Iterate.
5655
57- ## Prefer the good over the perfect
56+ ## Prefer the Good Over the Perfect
5857
59- Your documentation should be as good as possible within a reasonable time frame.
60- The standards for a documentation review are different from the
61- standards for code reviews. Reviewers can and should ask for improvements, but
62- in general, the author should always be able to invoke the "Good Over Perfect
63- Rule". It's preferable to allow authors to quickly submit changes that improve
64- the document, instead of forcing rounds of review until it's "perfect". Docs are
65- never perfect, and tend to gradually improve as the team learns what they really
66- need to write down.
58+ Documentation is an art. There is no perfect document, there are only proven
59+ methods and prudent guidelines. See [ Better is better than best] ( ./style.md ) .
6760
68- ## Documentation is the story of your code
61+ ## Documentation is the Story of Your Code
6962
70- Writing excellent code doesn't end when your code compiles or even if your
71- test coverage reaches 100%. It's easy to write something a computer understands,
72- it's much harder to write something both a human and a computer understand. Your
63+ Writing excellent code doesn't end when your code compiles or even if your test
64+ coverage reaches 100%. It's easy to write something a computer understands, it's
65+ much harder to write something both a human and a computer understand. Your
7366mission as a Code Health-conscious engineer is to ** write for humans first,
7467computers second.** Documentation is an important part of this skill.
7568
7669There's a spectrum of engineering documentation that ranges from terse comments
7770to detailed prose:
7871
79- 1 . ** Inline comments** : The primary purpose of inline comments is to provide
72+ 1 . ** Meaningful names** : Good naming allows the code to convey information that
73+ would otherwise be relegated to comments or documentation. This includes
74+ nameable entities at all levels, from local variables to classes, files, and
75+ directories.
76+
77+ 2 . ** Inline comments** : The primary purpose of inline comments is to provide
8078 information that the code itself cannot contain, such as why the code is
8179 there.
8280
83- 2 . ** Method and class comments** :
81+ 3 . ** Method and class comments** :
8482
85- * ** Method API documentation** : The header / Javadoc / docstring
86- comments that say what methods do and how to use them. This
87- documentation is ** the contract of how your code must behave** . The
88- intended audience is future programmers who will use and modify your
89- code.
83+ * ** Method API documentation** : The header / Javadoc / docstring comments
84+ that say what methods do and how to use them. This documentation is
85+ ** the contract of how your code must behave** . The intended audience is
86+ future programmers who will use and modify your code.
9087
9188 It is often reasonable to say that any behavior documented here should
9289 have a test verifying it. This documentation details what arguments the
@@ -103,13 +100,42 @@ to detailed prose:
103100 examples of how you might use the class / file.
104101
105102 Examples are particularly relevant when there's several distinct ways to
106- use the class (some advanced, some simple). Always list the simplest
107- use case first.
103+ use the class (some advanced, some simple). Always list the simplest use
104+ case first.
108105
109- 3 . ** README.md** : A good README.md orients the new user to the directory and
106+ 4 . ** README.md** : A good README.md orients the new user to the directory and
110107 points to more detailed explanation and user guides:
111- * What is this directory intended to hold?
112- * Which files should the developer look at first? Are some files an API?
113- * Who maintains this directory and where I can learn more?
108+
109+ * What is this directory intended to hold?
110+ * Which files should the developer look at first? Are some files an API?
111+ * Who maintains this directory and where I can learn more?
114112
115113 See the [ README.md guidelines] ( READMEs.md ) .
114+
115+ 5 . ** docs** : The contents of a good docs directory explain how to:
116+
117+ * Get started using the relevant API, library, or tool.
118+ * Run its tests.
119+ * Debug its output.
120+ * Release the binary.
121+
122+ 6 . ** Design docs, PRDs** : A good design doc or PRD discusses the proposed
123+ implementation at length for the purpose of collecting feedback on that
124+ design. However, once the code is implemented, design docs should serve as
125+ archives of these decisions, not as half-correct docs (they are often
126+ misused).
127+
128+ 7 . ** Other external docs** : Some teams maintain documentation in other
129+ locations, separate from the code, such as Google Sites, Drive, or wiki.
130+ If you do maintain documentation in
131+ other locations, you should clearly point to those locations from your
132+ project directory (for example, by adding an obvious link to the location
133+ from your project's ` README.md ` ).
134+
135+ ## Duplication is Evil
136+
137+ Do not write your own guide to a common Google technology or process. Link to it
138+ instead. If the guide doesn't exist or it's badly out of date, submit your
139+ updates to the appriopriate directory or create a package-level
140+ README.md. ** Take ownership and don't be shy** : Other teams will usually welcome
141+ your contributions.
0 commit comments