Permalink
Browse files

incorporate some ideas from Andrew Eddie, most notably section number…

…ing and the 'Files' section
  • Loading branch information...
1 parent 8a63271 commit 236f82d30998a73ddfa91b546300e31db80e5a90 @pmjones pmjones committed May 7, 2012
Showing with 107 additions and 70 deletions.
  1. +54 −21 proposed/PSR-1-basic.md
  2. +53 −49 proposed/PSR-2-advanced.md
View
@@ -1,9 +1,12 @@
Basic Coding Standard
=====================
+This section of the standard comprises what should be considered the mandatory
+styling elements that are required to ensure a high level of technical
+interoperability between shared PHP code.
-Overview
---------
+1. Overview
+-----------
- Use only <?php and <?= tags.
@@ -16,26 +19,21 @@ Overview
- Declare method names in `camelCase`.
-General
--------
+2. Files
+--------
-### PHP Tags
+### 2.1. PHP Tags
Use the long `<?php ?>` tags for PHP code. Use of short-echo `<?= ?>` tags is
also allowed. Do not use the other tag variations.
-### Character Encoding
+### 2.2. Character Encoding
Use only UTF-8 (no BOM) for PHP code. Do not use other character encodings.
-`namespace` and `class`
------------------------
-
-> N.b.: Formal namespaces were introduced in PHP 5.3. Code written for 5.2.x
-> and before must use the pseudo-namespacing convention of `Vendor_`
-> prefixes on class names. Code written for PHP 5.3 and after must use
-> formal namespaces.
+3. Namespace and Class Names
+----------------------------
All namespaces and classes are to be named with [PSR-0][] in mind. This means
each class is in a file by itself, and is in a namespace of at least one
@@ -45,18 +43,53 @@ level: a top-level vendor name.
Declare class names in `StudlyCaps`.
+For example:
+
+```php
+<?php
+// PHP 5.3 and later:
+namespace Vendor\Model;
+
+class Foo
+{
+}
+```
+
+Formal namespaces were introduced in PHP 5.3. Code written for 5.2.x
+and before must use the pseudo-namespacing convention of `Vendor_`
+prefixes on class names. Code written for PHP 5.3 and after must use
+formal namespaces.
+
+```php
+<?php
+// PHP 5.2.x and earlier:
+class Vendor_Model_Foo
+{
+}
+```
+
+4. Class Constants, Properties, and Methods
+-------------------------------------------
+
+The term "class" refers to all classes, interfaces, and traits.
+
-Class Constants, Properties, and Methods
-----------------------------------------
+### 4.1. Constants
-> N.b.: The term "class" refers to all classes, interfaces, and traits.
+Declare class in all upper case with underscore separators. For example:
-### Constants
+```php
+<?php
+namespace Vendor\Model;
-Declare class in all upper case with underscore separators; e.g.,
-`CONSTANT_NAME`.
+class Foo
+{
+ const VERSION;
+ const DATE_APPROVED;
+}
+```
-### Properties
+### 4.2. Properties
This guide expressly avoids any recommendation regarding the use of
`$StudlyCaps`, `$camelCase`, or `$under_score` property names.
@@ -69,6 +102,6 @@ Whatever naming convention is used must be applied consistently within a
reasonable scope. That scope may be vendor-level, package-level, class-level,
or method-level.
-### Methods
+### 4.3. Methods
Declare method names in `camelCase()`.
View
@@ -15,8 +15,8 @@ the benefit of this guide is not in the rules themselves, but in the sharing
of those rules.
-Overview
---------
+1. Overview
+-----------
- Follow [PSR-1][].
@@ -47,59 +47,61 @@ Overview
closing parentheses for control structures have no space before.
-General
--------
+2. General
+----------
-### Basic Coding Standard
+### 2.1 Basic Coding Standard
Follow all rules outlined in PSR-1 "Basic Coding Standard".
-### Closing Tag
-
-In files that contain only PHP, omit the closing `?>` tag.
-
+### 2.2 Files
-### Indenting
+Use the Unix LF (linefeed) line ending on all PHP files.
-Use an indent of 4 spaces. Do not use tabs.
+End each file with a single blank line.
-> N.b.: Using only spaces, and not mixing spaces with tabs, helps to avoid
-> problems with diffs, patches, history, and annotations. The use of spaces
-> also makes it easy to insert fine-grained sub-indentation for inter-line
-> alignment.
+In files that contain only PHP, omit the closing `?>` tag.
+### 2.3 Lines
-### Lines
+There is no hard limit on line length.
-There is no hard limit on line length. The soft limit on line length is 120
-characters; automated style checkers must warn but not error at the soft
-limit. This guide encourages lines no longer than 80 characters, and
-encourages splitting longer lines into multiple subsequent lines of no more
-than 80 characters each.
+The soft limit on line length is 120 characters; automated style checkers must
+warn but not error at the soft limit.
-Use the Unix LF (linefeed) line ending on all PHP files.
+This guide encourages lines no longer than 80 characters, and encourages
+splitting longer lines into multiple subsequent lines of no more than 80
+characters each.
Do not add trailing spaces at the end of lines.
-Blank lines may be added to improve readability and to indicate related blocks
-of code.
+Blank lines may be added to improve readability and to indicate related
+blocks of code.
Use at most one statement per line.
-End each file with a single blank line.
+### 2.4 Indenting
+Use an indent of 4 spaces. Do not use tabs.
+
+> N.b.: Using only spaces, and not mixing spaces with tabs, helps to avoid
+> problems with diffs, patches, history, and annotations. The use of spaces
+> also makes it easy to insert fine-grained sub-indentation for inter-line
+> alignment.
-`namespace` and `use`
----------------------
+
+3. Namespace and Use Declarations
+---------------------------------
Place one blank line after the `namespace` declaration.
All `use` declarations go after the `namespace` declaration. There is one
`use` keyword per declaration.
Place one blank line after the `use` block.
-
+
+For example:
```php
<?php
@@ -114,10 +116,12 @@ use OtherVendor\OtherPackage\BazClass;
```
-Classes, Properties, and Methods
---------------------------------
+4. Classes, Properties, and Methods
+-----------------------------------
+
+The term "class" refers to all classes, interfaces, and traits.
-> N.b.: The term "class" refers to all classes, interfaces, and traits.
+### 4.1. Extends and Implements
Declare `extends` and `implements` keywords on the same line as the class
name.
@@ -159,7 +163,7 @@ class ClassName extends ParentClass implements
}
```
-### Properties
+### 4.2. Properties
Declare visibility on all properties. Do not use `var` to declare a property.
Declare only one property per statement.
@@ -176,7 +180,7 @@ class ClassName
}
```
-### Methods
+### 4.3 Methods
Declare visibility on all methods.
@@ -204,7 +208,7 @@ class ClassName
}
```
-### Method Arguments
+### 4.3 Method Arguments
Method arguments with default values always go at the end of the argument
list.
@@ -242,7 +246,7 @@ class ClassName
}
```
-### `abstract`, `final`, and `static`
+### 4.4. `abstract`, `final`, and `static`
When present, the `abstract` and `final` declarations precede the visibility
declaration.
@@ -267,8 +271,8 @@ class ClassName
```
-Control Structures
-------------------
+5. Control Structures
+---------------------
The general style rules for control structures are as follows:
@@ -284,7 +288,7 @@ the structures look, and reduces the likelihood of introducing errors as new
lines get added to the body.
-### `if`, `elseif`, `else`
+### 5.1. `if`, `elseif`, `else`
An `if` structure looks like the following. Note the placement of parentheses,
spaces, and braces; and that `else` and `elseif` are on the same line as the
@@ -307,7 +311,7 @@ if ($expr1) {
> like single words.
-### `switch`, `case`
+### 5.2. `switch`, `case`
A `switch` structure looks like the following. Note the placement of
parentheses, spaces, and braces; the indent levels for `case` and `break`; and
@@ -328,7 +332,7 @@ switch ($expr) {
}
```
-### `while`, `do while`
+### 5.3 `while`, `do while`
A `while` statement looks like the following. Note the placement of
parentheses, spaces, and braces.
@@ -350,7 +354,7 @@ do {
} while ($expr);
```
-### `for`
+### 5.4. `for`
A `for` statement looks like the following. Note the placement of parentheses,
spaces, and braces.
@@ -362,7 +366,7 @@ for ($i = 0; $i < 10; $i++) {
}
```
-### `foreach`
+### 5.5. `foreach`
A `foreach` statement looks like the following. Note the placement of
parentheses, spaces, and braces.
@@ -374,7 +378,7 @@ foreach ($iterable as $key => $value) {
}
```
-### `try`, `catch`
+### 5.6. `try`, `catch`
A `try catch` block looks like the following. Note the placement of
parentheses, spaces, and braces.
@@ -390,8 +394,8 @@ try {
}
```
-Conclusion
-----------
+6. Conclusion
+--------------
There are many elements of style and practice intentionally omitted by this
guide; these include but are not limited to:
@@ -415,10 +419,10 @@ Future PSRs may revise and extend this guide to address those or other
elements of style and practice.
-Appendices
-----------
+7. Appendices
+-------------
-### Survey Data
+### 7.1 Survey Data
url,http://www.horde.org/apps/horde/docs/CODING_STANDARDS,http://pear.php.net/manual/en/standards.php,http://solarphp.com/manual/appendix-standards.style,http://framework.zend.com/manual/en/coding-standard.html,http://symfony.com/doc/2.0/contributing/code/standards.html,http://www.ppi.io/docs/coding-standards.html,https://github.com/ezsystems/ezp-next/wiki/codingstandards,http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html,https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Coding,http://drupal.org/coding-standards,http://code.google.com/p/sabredav/,http://area51.phpbb.com/docs/31x/coding-guidelines.html,https://docs.google.com/a/zikula.org/document/edit?authkey=CPCU0Us&hgd=1&id=1fcqb93Sn-hR9c0mkN6m_tyWnmEvoswKBtSc0tKkZmJA,http://www.chisimba.com,n/a,https://github.com/Respect/project-info/blob/master/coding-standards-sample.php,n/a,Object Calisthenics for PHP,http://doc.nette.org/en/coding-standard,http://flow3.typo3.org,https://github.com/propelorm/Propel2/wiki/Coding-Standards,http://developer.joomla.org/coding-standards.html
voting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yes
@@ -445,7 +449,7 @@ Appendices
class_method_control_brace,next/next/same,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/next,same/same/same,same/same/same,same/same/same,same/same/same,next/next/next,next/next/same,next/same/same,next/next/next,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/same,next/next/next
-### Survey Results
+### 7.2 Survey Results
indent_type:
tab: 7

0 comments on commit 236f82d

Please sign in to comment.