Reviewing Guidelines
~~~~~~~~~~~~~~~~~~~~

This document describes which things to specially pay attention to when
reviewing components. By adhering to these guidelines we make sure we have a
consistent set of components.

Structure
---------
- Directory structure should be the "new" one, and not the one where each word
  *has* to be separation by a new directory marker.

Documentation
-------------
- Make sure the documentation for parameters use "integer", "float", "number"
  (if it can be a float or integer), "string", "array", "array(<type)",
  "<objectname>" or "resource".
- The documentation is not to have any warnings anymore
- See for proper doc blocks:
  http://lists.ez.no/pipermail/components/2005-October/000491.html

Parameters
----------
- All optional arguments not having a boolean as default argument should use
  "null" as default argument and not "false".

Messages
--------
- All error messages' parameters must be enclosed in ' '. A typical error
  message is build with the CS below. This means: use " and {} to enclose
  variables. ::

    "The file could not be stored in '{$this->path}'"

- Exceptions should be documented in ALL methods, even if a function does not
  contain a throw() statement but calls a function which can throw an
  exception.

Options
-------
Check whether options to classes are set with the following rules:

- Required options should be passed in the constructor, with possible default
  arguments. (Use null over false to signal that one can be totally away)
- The $options array should be the last argument.
- Retrieving currently set required options is done with specialized
  methods.
- Retrieving currently set optional options is done with getOptions().
- setOptions() should look like something like this: ::

    /**
     * Sets the current options for the writer.
     *
     * @param array $configurationData An associative array of options for the writer.
     */
    public function setOptions( $configurationData )
    {
        foreach ( $configurationData as $name => $value )
        {
            switch ( $name )
            {
                case 'useComments':
                    if ( gettype( $value ) != 'boolean' )
                    {
                        throw new ezcBaseConfigException( $name, ezcBaseConfigException::VALUE_OUT_OF_RANGE, $value );
                    }
                    $this->useComments = $value;
                    break;
                case 'permissions':
                    if ( gettype( $value ) != 'integer' )
                    {
                        throw new ezcBaseConfigException( $name, ezcBaseConfigException::VALUE_OUT_OF_RANGE, $value );
                    }
                    if ( $value < 0 || $value > 0777 )
                    {
                        throw new ezcBaseConfigException( $name, ezcBaseConfigException::VALUE_OUT_OF_RANGE, $value );
                    }
                    $this->permissions = $value;
                    break;
                default:
                    throw new ezcBaseConfigException( $name, ezcBaseConfigException::UNKNOWN_CONFIG_SETTING );
            }
        }
    }
 

Singleton Usage
---------------

Should use the *exactly* following syntax: ::

    /**
     * @param ezcTranslationFilterBork Instance
     */
    static private $instance = null;

    /**
     * Private constructor to prevent non-singleton use
     */
    private function __constructor()
    {
    }

    /**
     * Returns an instance of the class ezcTranslationFilterBork
     *
     * @returns ezcTranslationFilterBork Instance of ezcTranslationFilterBork
     */
    public static function getInstance()
    {
        if ( is_null( self::$instance ) )
        {
            self::$instance = new ezcTranslationBorkFilter();
        }
        return self::$instance;
    }


..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79