compared with
Current by Denis Portnov
on May 03, 2012 18:21.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (42)

View Page History
{note:title=Work in Progress}
<ac:macro ac:name="note"><ac:parameter ac:name="title">Work in Progress</ac:parameter><ac:rich-text-body>
<p>This page is work in progress. Please discuss and feel free to edit, rephrase, extend with more cases and examples.</p></ac:rich-text-body></ac:macro>
{note}

This RFC contains a proposal for several additions to current [ZF2 Coding Standards|http://framework.zend.com/wiki/x/yQCvAg] regarding class naming and class file location.
<p>This RFC contains a proposal for several additions to current <a href="http://framework.zend.com/wiki/x/yQCvAg">ZF2 Coding Standards</a> regarding class naming and class file location.</p>

<p>Conventions of this document:</p>
<ul>
<li><code>ComponentX</code> - component of ZF2, top level class</li>
<li><code>SubcomponentX</code> - subcomponent ComponentX</li>
<li><code>PluginX</code> - loadable plugin for component or subcomponent (Adapter, Reader, Writer etc)</li>
</ul>


Conventions of this document:
* {{ComponentX}} - component of ZF2, top level class
* {{SubcomponentX}} - subcomponent ComponentX
* {{PluginX}} - loadable plugin for component or subcomponent (Adapter, Reader, Writer etc)
<h2>Requirements</h2>
<p>This section proposes standards to be marked as <strong>MUST</strong>, <strong>MUST NOT</strong>, <strong>SHOULD</strong> and <strong>SHOULD NOT</strong> in CS docs. But after discussion some requirements could become recommendations. </p>

h2. Requirements
This section proposes standards to be marked as *MUST*, *MUST NOT*, *SHOULD* and *SHOULD NOT* in CS docs. But after discussion some requirements could become recommendations.
<h3>Options</h3>
h3. Options
Options {{extends Stdlib\Options}} <p>Options <code>extends Stdlib\Options</code> class should be prefixed with instance it configures ({{AdapterOptions}}) (<code>AdapterOptions</code>) and should live in same namespace as instance class. </p>
{code:php}
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX;

{}

{code}
]]></ac:plain-text-body></ac:macro>

<p>There should be no class named {{Config}} <code>Config</code> to avoid confusion with {{Options}}. <code>Options</code>. If "config" &quot;config&quot; is a valid term in component's knowledge domain, class name should be prefixed with some word expressing purpose of the config class. </p>

h3. Exceptions
<h3>Exceptions</h3>
<p>Exception classes including ExceptionInterface live in Exception subnamespace of the component ({{ComponentX\Exception\ExceptionInterface}}). (<code>ComponentX\Exception\ExceptionInterface</code>). </p>

<p>Subcomponents that define their own exceptions follow same rule. Exceptions for the subcomponents should extend main cimponent's exceptions</p>

{code:php}
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX\Exceptions;

interface ExceptionInterface
{}
{code}
]]></ac:plain-text-body></ac:macro>

{code:php}
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX\SubcomponentY\Exceptions;

interface ExceptionInterface extends ComponentXExceptionInterface
{}
{code}
]]></ac:plain-text-body></ac:macro>

h3. Pugin Boker and Loader
Plugin loading related classes ( {{PluginBroker}}, {{PluginLoader}} ) should leave one namespace above Plugin class.
{code:php}
<h3>Pugin Boker and Loader</h3>
<p>Plugin loading related classes ( <code>PluginBroker</code>, <code>PluginLoader</code> ) should leave one namespace above Plugin class.</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX\Adapter

class FileAdapter
{}

namespace ComponentsX\Adapter;

class FileAdapter
{}

namespace ComponentsX;

class FileAdapterBroker extends PluginBroker
{}
class FileAdapterLoader extends PluginLoader
{}
{code}
]]></ac:plain-text-body></ac:macro>

h2. Recommendations
This sections proposes recommendations to be marked as *MAY* in CS docs.
<h2>Recommendations</h2>
<p>This sections proposes recommendations to be marked as <strong>MAY</strong> in CS docs.</p>


h3. Factories
+TBD+ <h3>Factories</h3>
<ul>
<li>Factory class that creates only one type of instance may be prefixed with instance name.
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX;

class ComponentsXFactory
{
public static function create()
{}
}
]]></ac:plain-text-body></ac:macro></li>
</ul>


<ul>
<li>class that creates several types of instances should be not prefixed
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX;

class ComponentsXFactory
{
public static function createComponentX()
{}

public static function createAdapter()
{}
}
]]></ac:plain-text-body></ac:macro></li>
</ul>