|
| 1 | +# Style Guide |
| 2 | + |
| 3 | +> Style guide for writing text. |
| 4 | +
|
| 5 | + |
| 6 | +* Filenames should be lowercase. Some top-level files and all `README.md` files are exceptions. |
| 7 | + |
| 8 | +* Filenames should be snake_case. |
| 9 | + |
| 10 | +* Use American English spelling; e.g., "Capitalize" vs. "Capitalise", "color" vs. "colour", etc. |
| 11 | + |
| 12 | +* Insofar as is possible, spelling and grammar issues should be identified using tools, and, if not caught by a tool, should be identified by human reviewers. |
| 13 | + |
| 14 | +* Use the [Oxford comma][oxford-comma] for clarity. |
| 15 | + |
| 16 | +* Avoid using personal pronouns in reference documentation (e.g., "I", "you", "we"). |
| 17 | + |
| 18 | +* Personal pronouns are acceptable in more colloquial documentation, such as guides. |
| 19 | + |
| 20 | +* Prefer using gender-neutral pronouns and mass nouns. For example, |
| 21 | + |
| 22 | + - __OK__: "one", "they", "their", "them", "people", "developers" |
| 23 | + - __NOT OK__: "his", "him", "guys" |
| 24 | + |
| 25 | + Exclusive use of female pronoun forms is permitted. |
| 26 | + |
| 27 | +* Place end-of-sentence punctuation inside wrapping elements; e.g., periods should be placed inside parentheses and quotes, not after. |
| 28 | + |
| 29 | +* Markdown documents must start with a level-one heading, such as in this document. |
| 30 | + |
| 31 | +* Use definitions rather than in-lining; e.g., prefer `[link][]` over `[link](http://example.com)`. |
| 32 | + |
| 33 | +* References to constructor functions should use PascalCase. |
| 34 | + |
| 35 | +* References to constructor instances should use camelCase. |
| 36 | + |
| 37 | +* References to functions and methods should use parentheses; e.g., `foo.factory()` versus `foo.factory`. |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +<section class="links"> |
| 42 | + |
| 43 | +[oxford-comma]: https://en.wikipedia.org/wiki/Serial_comma |
| 44 | + |
| 45 | +</section> |
| 46 | + |
| 47 | +<!-- /.links --> |
0 commit comments