added a document about code conventions

Author: fabpot

contributing/code/conventions.rst

@@ -0,0 +1,58 @@
+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.
+
+Method Names
+------------
+
+When an object has a "main" many relation with related "things"
+(objects, parameters, ...), the method names are normalized:
+
+  * ``get()``
+  * ``set()``
+  * ``has()``
+  * ``all()``
+  * ``replace()``
+  * ``remove()``
+  * ``clear()``
+  * ``isEmpty()``
+  * ``add()``
+  * ``register()``
+  * ``count()``
+  * ``keys()``
+
+The usage of these methods are only allowed when it is clear that there
+is a main relation:
+
+* a ``CookieJar`` has many ``Cookie``s;
+
+* a Service ``Container`` has many services and many parameters (as services
+  is the main relation, we use the naming convention for this relation);
+
+* a Console ``Input`` has many arguments and many options. There is no "main"
+  relation, and so the naming convention does not apply.
+
+For many relations where the convention does not apply, the following methods
+must be used instead (where ``XXX`` is the name of the related thing):
+
+============== =================
+Main Relation  Other Relations
+============== =================
+``get()``      ``getXXX()``
+``set()``      ``setXXX()``
+``has()``      ``hasXXX()``
+``all()``      ``getXXXs()``
+``replace()``  ``setXXXs()``
+``remove()``   ``removeXXX()``
+``clear()``    ``clearXXX()``
+``isEmpty()``  ``isEmptyXXX()``
+``add()``      ``addXXX()``
+``register()`` ``registerXXX()``
+``count()``    ``countXXX()``
+``keys()``     n/a
+============== =================

contributing/code/index.rst

@@ -7,6 +7,7 @@ Contributing Code
     bugs
     patches
     security
-    standards
     tests
+    standards
+    conventions
     license

contributing/map.rst.inc

@@ -3,8 +3,9 @@
   * :doc:`Bugs </contributing/code/bugs>` | 
   * :doc:`Patches </contributing/code/patches>` | 
   * :doc:`Security </contributing/code/security>` | 
-  * :doc:`Coding Standards</contributing/code/standards>` | 
   * :doc:`Tests </contributing/code/tests>` | 
+  * :doc:`Coding Standards</contributing/code/standards>` | 
+  * :doc:`Code Conventions</contributing/code/conventions>` | 
   * :doc:`License </contributing/code/license>`
 
 * **Documentation**: