doc:howto:styleguide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
doc:howto:styleguide [2011/07/10 22:42] – added a "common mistakes" section philipdoc:howto:styleguide [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-==== Style Guide ==== +This page has been removedin favor of [[http://doc.php.net/tutorial/style.php|new guide]]
-This style guide affects the PHP Manual. +
- +
-=== Reference === +
-We follow the following style guide as a base: +
- +
-  * A first-person active voice is preferredwhich also means do not address the reader directly as "You" +
-  * We follow the [[http://fedoraproject.org/wiki/DocsProject/StyleGuide|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 [[http://pear.php.net/manual/en/standards.php|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)