incubator-zeta-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject [zeta-commits] svn commit: r1039656 - /incubator/zetacomponents/docs/guidelines/implementation.txt
Date Sat, 27 Nov 2010 11:34:00 GMT
Author: toby
Date: Sat Nov 27 11:34:00 2010
New Revision: 1039656

URL: http://svn.apache.org/viewvc?rev=1039656&view=rev
Log:
- Added: Section about our coding standard.
# Please review!

Modified:
    incubator/zetacomponents/docs/guidelines/implementation.txt

Modified: incubator/zetacomponents/docs/guidelines/implementation.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/docs/guidelines/implementation.txt?rev=1039656&r1=1039655&r2=1039656&view=diff
==============================================================================
--- incubator/zetacomponents/docs/guidelines/implementation.txt (original)
+++ incubator/zetacomponents/docs/guidelines/implementation.txt Sat Nov 27 11:34:00 2010
@@ -1167,6 +1167,171 @@ There is no workaround for this at the m
 original string and the lowercase string at the same time or using only
 lowercase characters at all times.
 
+
+Coding standard
+===============
+
+The Zeta coding standard is derived from the coding guidelines used in eZ
+Publish. It may feel uncommon to you, if you coded in the manner of PEAR
+before, but it feels a lot more readable, once you get used to it. Please stick
+to the following rules, when you provide code to Apache Zeta Components.
+
+Names
+-----
+
+All names are in nerdCase (headless camel case). This applies to variable,
+property, function method and also class names. Examples are::
+
+    class ezcWebdavTransport
+
+    static public $parsingMap = array();
+
+    public final function parseRequest( $uri )
+
+    $response->validateHeaders();
+
+Note that class names always start with the prefix ``ezc``, so the actual name
+of the class is in CamelCase. The only exception for this naming rule are class
+constants, which are written fully in UPPERCASE and, if they consist of
+multiple words, are devided by underscores (``_``). For example::
+
+    const VERSION = '//autogentag//';
+
+    const XML_DEFAULT_NAMESPACE = 'DAV:';
+
+For conventions on names, please rever to the `Naming conventions`_ section.
+
+Brackets
+--------
+
+There are three simple rules on how you need to handle brackets:
+
+Parenthesis
+~~~~~~~~~~~
+
+After every opening parenthesis and before every closing parenthesis there is a
+whitespace::
+
+    if ( ( $someThing === 'some' || $anotherThing === 'another' ) )
+
+The whitespace is typically a simple space character, but might also be a
+newline, if you need to indent code in parenthesis.
+
+Square brackets
+~~~~~~~~~~~~~~~
+
+There is no space after an opening square bracket and none before the closing
+conterpart::
+
+    $this->properties['namespaceRegistry'] = null;
+
+Curly brackets
+~~~~~~~~~~~~~~
+
+Every curly bracket is preceeded and followed by a newline::
+
+    public final function parseRequest( $uri )
+    {
+        // …
+        if ( isset( self::$parsingMap[$_SERVER['REQUEST_METHOD']] )  )
+        {
+            try
+            {
+                // …
+            }
+            catch ( Exception $e )
+            {
+                // …
+            }
+        }
+        // …
+    }
+
+The only exception for this rule are curly brackets inside double quoted
+strings, which are used to mark a variable replacement::
+
+    $foo "This is a {$foo} string with {$bar[23]}";
+
+Line length
+-----------
+
+A code line should not be longer than 80 characters. In case a line in your
+source code becomes longer, you need to wrap it and use proper `Indentation`_.
+
+Proper wrapping and indentation depends on the situation. For example, for a
+method signature, a proper wrapping would be::
+
+    public function doSomething(
+        ezcSomeClass $foo,
+        ezcAnotherClass $bar,
+        $doItRight = true,
+        $someIntValue = 10
+    )
+
+In case of a long condition, you should try to group the condition elements
+semantically, as good as possible::
+
+    if ( ( $someThing === 'some' || $anotherThing === 'another' )
+        && ( $foo !== $bar ) )
+
+Indentation
+-----------
+
+Indentation is performed by **four spaces**, tabs or a different ammount of
+spaces for indentation is not allowed. Code blocks are indented in two
+different cases:
+
+1. After an opening curly bracket
+2. In case a code line becomes to long
+
+Properly indented code looks like this::
+
+    public final function parseRequest( $uri )
+    {
+        $body = $this->retrieveBody();
+        $path = $this->retrievePath( $uri );
+
+        if ( isset( self::$parsingMap[$_SERVER['REQUEST_METHOD']] )  )
+        {
+            try
+            {
+                // Plugin hook beforeParseRequest
+                ezcWebdavServer::getInstance()->pluginRegistry->announceHook(
+                    __CLASS__,
+                    'beforeParseRequest',
+                    new ezcWebdavPluginParameters(
+                        array(
+                            'path' => &$path,
+                            'body' => &$body,
+                        )
+                    )
+                );
+
+                $request = call_user_func(
+                    array( $this, self::$parsingMap[$_SERVER['REQUEST_METHOD']] ),
+                    $path,
+                    $body
+                );
+            }
+            catch ( Exception $e )
+            {
+                return $this->handleException( $e, $uri );
+            }
+        }
+        // …
+
+Operators
+---------
+
+Before and after any operator there must be a space::
+
+    $foo = 23 * 42;
+    $bar = 'Some' . ' ' . 'thing';
+
+There is no space before a comma (``,``)::
+
+    $this->doSomething( $foo, $bar, $baz );
+
 Documentation
 =============
 



Mime
View raw message