Merge pull request symfony#508 from Seldaek/cs

weaverryan · weaverryan · commit 57ff6d68f95d · 2011-07-06T15:35:29.000-07:00
Add code sample and some more details to the CS page
diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst
@@ -4,8 +4,8 @@ Conventions
 The :doc:`standards` document describes the coding standards for the Symfony2
 projects and the internal and third-party bundles. This document describes
 coding standards and conventions used in the core framework to make it more
-consistent and predictable. You can follow them in your own code, but you
-don't need to.
+consistent and predictable. You are encouraged to follow them in your own
+code, but you don't need to.
 
 Method Names
 ------------
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
@@ -2,8 +2,60 @@ Coding Standards
 ================
 
 When contributing code to Symfony2, you must follow its coding standards. To
-make a long story short, here is the golden rule: *Imitate the existing
-Symfony2 code*.
+make a long story short, here is the golden rule: **Imitate the existing
+Symfony2 code**. Most open-source Bundles and libraries used by Symfony2 also
+follow the same guidelines, and you should too.
+
+Remember that the main advantage of standards is that every piece of code
+looks and feels familiar, it's not about this or that being more readable.
+
+Since a picture - or some code - is worth a thousand words, here's a short
+example containing most features described below:
+
+.. code-block:: php
+
+    <?php
+
+    /*
+     * This file is part of the Symfony package.
+     *
+     * (c) Fabien Potencier <fabien@symfony.com>
+     *
+     * For the full copyright and license information, please view the LICENSE
+     * file that was distributed with this source code.
+     */
+
+    namespace Acme;
+
+    class Foo
+    {
+        const SOME_CONST = 42;
+
+        private $foo;
+
+        /**
+         * @param string $dummy Some argument description
+         */
+        public function __construct($dummy)
+        {
+            $this->foo = $this->transform($dummy);
+        }
+
+        /**
+         * @param string $dummy Some argument description
+         * @return string|null Transformed input
+         */
+        private function transform($dummy)
+        {
+            if (true === $dummy) {
+                return;
+            } elseif ('string' === $dummy) {
+                $dummy = substr($dummy, 0, 5);
+            }
+
+            return $dummy;
+        }
+    }
 
 Structure
 ---------
@@ -35,8 +87,8 @@ Structure
 * Put braces on their own line for classes, methods, and functions
   declaration;
 
-* Separate the conditional statement and the opening brace with a single
-  space and no blank line;
+* Separate the conditional statements (`if`, `else`, ...) and the opening
+  brace with a single space and no blank line;
 
 * Declare visibility explicitly for class, methods, and properties (usage of
   `var` is prohibited);
@@ -68,9 +120,18 @@ Naming Conventions
 
 * Use alphanumeric characters and underscores for file names;
 
+* Don't forget to look at the more verbose :doc:`conventions` document for
+  more subjective naming considerations.
+
 Documentation
 -------------
 
 * Add PHPDoc blocks for all classes, methods, and functions;
 
 * The `@package` and `@subpackage` annotations are not used.
+
+License
+-------
+
+* Symfony is released under the MIT license, and the license block has to be
+  present at the top of every PHP file, before the namespace.
