doc:howto:styleguide
This is an old revision of the document!
Style Guide
This style guide affects the PHP Manual.
Reference
We follow the following style guide as a base:
- A first-person active voice is preferred, which also means do not address the reader directly as “You”
- We follow the Fedora Style Guide
Conventions specific to the PHP Manual
- The refpurpose should not end with a period
- Indenting is one space, and never tabs
- Whitespace changes should never be mixed with content changes
- Text that's repeated 3x or more should be defined as an entity within language-snippets.ent
- Many words, such as TRUE, FALSE, and NULL, should use the entity versions instead, like &true;
- Using <para> or <simpara> does not matter, but <para> is preferred
- Constants should be surrounded with <constant>, like <constant>PHP_EOL</constant>
- Functions should be surrounded with <function>, like <function>strlen</function> (Or, <methodname> for methods)
- Variables should be surrounded with <varname> like <varname>$foo</varname>
- ... Create “common docbook tag usages” instead of repeating....
- Examples should use the PEAR Coding Standards
Common mistakes
- Improper spacing. Mixing tabs with spaces, and indenting
- Long lines. Line width should not exceed 80 characters, although this is a loose requirement. 100 is probably fine, depending on the situation
- Committing leftover/bogus text that was generated using scripts/docgen/docgen.php. This should not be committed
- Windows line endings. Only use Unix line endings
- Having an IDE or Text editor remove trailing whitespace, then mixing it with commits. Don't do this
- Mixing &example.outputs.similar; and &example.outputs; entities. Use the former when the example output may differ, depending on the users usage/settings
doc/howto/styleguide.1310337726.txt.gz · Last modified: 2017/09/22 13:28 (external edit)