doc:howto:styleguide

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.txt · Last modified: 2011/07/11 00:42 by philip