Zend Framework 中的 Php 编码标准 (四) - 内嵌文档

最新推荐文章于 2024-04-18 15:13:13 发布

aqua_aqua

最新推荐文章于 2024-04-18 15:13:13 发布

阅读量1.3k

点赞数

分类专栏： PHP 文章标签： zend php interface exception parameters header

PHP 专栏收录该内容

6 篇文章 0 订阅

订阅专栏

原文： http://kbs.kimbs.cn/blog/list/post/26/title/zend-framework-coding-standards-for-php-inline-documentation

Zend Framework 中的 Php 编码标准 (四) - 内嵌文档

1. Docblocks start always with "/*" or "/**". The use of "#" is not allowed. The "//" is only allowed for comments within functions.

For example :

/**

* Class docblock

*/

class foo

{

     /* Variable docblock */

     public $foo ;

     /**

     * Function docblock

     */

     public function __construct ()

    {

         // Commentted hy '//' only allowed within function

         $this -> foo = 'foo' ;

         # Commentted by '#' is not allowed within function

         $this -> foo = 'bar' ;

    }

}

复制代码

2. A docblock must contain a short description and minimum one parameter. Optionally a long description and multiple parameters can be added.

For example :

/**

* One short description and one parameter at least

*

* @param

*/

/**

* Long description and multiple parameters below

*

* One empty line to seperate the

* SHORT_DESCRIPTION,

* LONG_DESCRIPTION,

* PARAMETERS

*

* @param

* @todo

*/

复制代码

3. All docblock parts which are not keywords have to be under each other with the same indenting.

For example :

/**

* Right

*

* @component All descriptive parts

* @uses have the same indenting

*/

/**

* Wrong

*

* @component All descriptive parts

* @uses don't have the same indenting

*/

复制代码

4. Also when describing parameters the keywords, parameters, and description have to have the same indenting to be under each other.

For example :

/**

* Right, all descriptions are indented

*

* @param string $value Description of this value

* @param integer $othervalue Another description

*/

/**

* Wrong, not indenting

*

* @param string $value Description of this value

* @param integer $othervalue Another description

*/

复制代码

5. Each file which is delivered with the Zend Framework must have the following header block :


 <?php
 
  /**
 
 * Zend Framework
 
 *
 
 * LICENSE
 
 *
 
 * This source file is subject to the new BSD license that is bundled
 
 * with this package in the file LICENSE.txt.
 
 * It is also available through the world-wide-web at this URL:
 
 * [url]http://framework.zend.com/license/new-bsd[/url]
 
 * If you did not receive a copy of the license and are unable to
 
 * obtain it through the world-wide-web, please send an email
 
 * to [email=license@zend.com]license@zend.com[/email] so we can send you a copy immediately.
 
 *
 
 * @category    Zend
 
 * @package     __PACKAGENAME__
 
 * @subpackage  __SUBPACKAGENAME__
 
 * @copyright   Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. ([url]http://www.zend.com[/url])
 
 * @license     [url]http://framework.zend.com/license/new-bsd[/url]     New BSD License
 
 * @version     $Id: $
 
 * @depreciated Since 0.0.1
 
 */

复制代码

This format can be used in any project, for example :


 <?php
 
  /**
 
 * Project name
 
 *
 
 * LICENSE
 
 *
 
 * License information
 
 * in multiple lines (maybe)
 
 *
 
 * @category    Category name
 
 * @package     Package of this file
 
 * @subpackage  Subpackage which include this file
 
 * @copyright   Copyright information
 
 * @license     License info for short
 
 * @version     $ Id and version description $
 
 * @depreciated Since xxx
 
 */

复制代码

6. When other filestypes are used like *.SH, *.BAT, *.JS and so on, the header block must also be contained as header comment. Only when a filetype does not support comments like *.CSS the header block can be omited.

For example :
// zf.bat

REM Zend Framework
REM
REM LICENSE
REM
REM This source file is subject to the new BSD license that is bundled
REM with this package in the file LICENSE.txt.
REM It is also available through the world-wide-web at this URL:
REM http://framework.zend.com/license/new-bsd
REM If you did not receive a copy of the license and are unable to
REM obtain it through the world-wide-web, please send an email
REM to license@zend.com so we can send you a copy immediately.
REM
REM Zend
REM Copyright (c) 2005-2009 Zend Technologies USA Inc. ( http://www.zend.com )
REM http://framework.zend.com/license/new-bsd New BSD License

// zf.sh

#############################################################################
# Zend Framework
#
# LICENSE
#
# This source file is subject to the new BSD license that is bundled
# with this package in the file LICENSE.txt.
# It is also available through the world-wide-web at this URL:
# http://framework.zend.com/license/new-bsd
# If you did not receive a copy of the license and are unable to
# obtain it through the world-wide-web, please send an email
# to license@zend.com so we can send you a copy immediately.
#
# Zend
# Copyright (c) 2005-2009 Zend Technologies USA Inc. ( http://www.zend.com )
# http://framework.zend.com/license/new-bsd New BSD License
#############################################################################

// *.js
The same with php files.

7. The @package clause has to be the component which this file is part of it, there must exist exact one @package clause per header.

For example :

/**

* ...

*

* @package    Zend_Controller

* @subpackage ...

* @copyright  ...

* @license    ...

*/

abstract class Zend_Controller_Router_Route_Abstract implements Zend_Controller_Router_Route_Interface

{

     // ...

}

复制代码

Another example :

/**

* ...

*

* @package    Zend_Db

* @subpackage ...

* @copyright  ...

* @license    ...

*/

class Zend_Db_Adapter_Mysqli extends Zend_Db_Adapter_Abstract

{

     // ...

}

复制代码

8. The @subpackage clause has to be a logical separation within this component. Logical separations occur when there are several directories which seperate parts of the same component. Only files which are in the main directory of the framework which is "Zend" can omit the subpackage. There must exist maximum one @subpackage clause per header.

First example :

/**

* @category   ...

* @package    ...

* @subpackage Adapter

* @copyright  ...

* @license    ...

*/

class Zend_Db_Adapter_Mysqli extends Zend_Db_Adapter_Abstract

{

     // ...

}

复制代码

Second example :

/**

* @category   ...

* @package    ...

* @subpackage Table

* @copyright  ...

* @license    ...

*/

class Zend_Db_Table_Select extends Zend_Db_Select

{

     // ...

}

复制代码

Third example for no subpackage :

/**

* @category   Zend

* @package    Zend_Auth

* @copyright  ...

* @license    ...

*/

class Zend_Auth

{

     // ...

}

复制代码

9. The @copyright clause has to include the actual year of the release of the framework.

For example :

/**

* @category   ...

* @package    ...

* @copyright  Copyright (c) 2005-2008 Zend ...

* @license    ...

*/

class Zend_Acl

{

     // ...

}

复制代码

10. If this file contains a depreciated class it must have the optional @depreciated clause.

For example :


 <?php
 
  /**
 
 * ...
 
 *
 
 * @depreciated Since 1.1.1
 
 */
 
  class  depreciateMe
 
  {
 
 }

复制代码

11. All classes/files which are required must contain a @see clause.

For example :

/**

* @see Zend_Controller_Dispatcher_Interface

*/

require_once 'Zend/Controller/Dispatcher/Interface.php' ;

复制代码

12. A class or interface in Zend Framework must have a class header which clauses must be added in the below seen order :

/**

* Description of the class

*

* More descriptive text which

* is allowed to span multiple lines

*

* @category    Zend

* @package     __PACKAGE__

* @subpackage  __SUBPACKAGE__

* @uses        __USES__

* @see         __SEE__

* @since       __SINCE__

* @copyright   Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. ([url]http://www.zend.com[/url])

* @license     [url]http://framework.zend.com/license/new-bsd[/url]     New BSD License

* @depreciated Since 0.0.1

*/

class Zend_Controller_Dispatcher extends Zend_Controller_Dispatcher_Class implements Zend_Controller_Dispatcher_Interface

复制代码

13. The @uses clause in header has to contain the extended or implemented classname. When multiple classes or interfaces are used, you must include a @uses clause for every class or interface. When no class is extended or interface is implemented then the @uses clause must be ommitted.

For example :

/**

* ...

*

* @uses       ArrayAccess

* @uses       Iterator

* @uses       Countable

* @package    ...

* @copyright  ...

* @license    ...

*/

class Zend_Dojo_Data implements ArrayAccess , Iterator , Countable

{

     // ...

}

复制代码

14. The @see clause in header is optional and can be added to link to another component within the framework. You can add multiple clauses.

For example :

/**

* ...

*

* @see        Zend_Parent

* @see        Zend_Interface

* @package    ...

* @copyright  ...

* @license    ...

*/

class Zend_Class extends Zend_Parent implements Zend_Interface

{

     // ...

}

复制代码

15. The @since clause can be added optionally to include the version since which this class is available. It must include the complete version number of the framework. Only one since clause is allowed to be added.

For example :

/**

* ...

*

* @category   ...

* @package    ...

* @copyright  ...

* @license    ...

* @since      Class available since Release 0.6.0

*

* @todo       ...

*/

class Zend_Console_Getopt

{

     // ...

}

复制代码

16. Each function must have a function header.

For example :

class Zend_Foo

{

     /**

     * Full text description of this function.

     * It described all possible things

     * but should not extend the line length of 100 characters.

     *

     * @param  boolean $value Value for checking

     * @since  Version 1.2.3

     * @see    Zend_Anything

     * @throws Zend_Exception When value is false

     * @return array

     */

     public function bar ( $value )

    {

        require_once( 'Zend/Anything.php' );

        if ( $value ) {

            return array( 'foo' => $value );

        } else {

            throw new Zend_Exception ( 'Throw me !' );

        }

    }

}

复制代码

17. All parameters of the function must be available. The types allowed are listed here :

(a) boolean
(b) integer
(c) string
(d) float
(e) array
(f) false
(g) true
(h) null
(i) Zend_Xxx (must be an existing class of the framework)

18. If more than one type could be used then the possible types have to be seperated with "|" like show above.

For example :

/**

* @param array|null $config configurations

*/

复制代码

19. If a parameter can be omitted the description must prepend a (optional) to the description.

For example :

/**

* @param array|null $config (optional) My optional value

*/

复制代码

20. If the function can throw an exception the @throws clause must be declared. Multiple exception types must be seperated with “|”. Also a description must be added why the exception is thrown.

For example :

class Zend_XmlRpc_Server extends Zend_Server_Abstract

{

     /**

     * Handle an xmlrpc call (actual work)

     *

     * @param  Zend_XmlRpc_Request $request

     * @return Zend_XmlRpc_Response

     * @throws Zend_XmlRpcServer_Exception|Exception

     * Zend_XmlRpcServer_Exceptions are thrown for internal errors; otherwise,

     * any other exception may be thrown by the callback

     */

     protected function _handle ( Zend_XmlRpc_Request $request )

    {

         // ...

     }

}

复制代码

21. A @return clause must always be defined. Only for class constructor and destructor the @return clause must be ommitted. If multiple types can be returned the types must be seperated with "|". An description can be appended, but is not necessary.

For example :

class Zend_Form implements Iterator , Countable , Zend_Validate_Interface

{

     /**

     * Overloading: access to elements, form groups, and display groups

     *

     * @param  string $name

     * @return Zend_Form_Element|Zend_Form|null

     */

     public function __get ( $name )

    {

         // ...

     }

}

复制代码

22. If the class itself is returned (fluid interface) then the description ”Provides a fluent interface“ must be added.

For example :

class Zend_Auth

{

     /**

     * Sets the persistent storage handler

     *

     * @param  Zend_Auth_Storage_Interface $storage

     * @return Zend_Auth Provides a fluent interface

     */

     public function setStorage ( Zend_Auth_Storage_Interface $storage )

    {

         $this -> _storage = $storage ;

        return $this ;

    }

}

复制代码

23. If the function does not return any value then the return value must be set to "void".

For example :

class Zend_Application

{

     /**

     * Run the application

     *

     * @return void

     */

     public function run ()

    {

         $this -> getBootstrap ()-> run ();

    }

}

复制代码

24. Keep in mind that the "void" and "null" are not the same. Null means that a empty variable is returned. But void means that nothing is returned. This is a small but important difference. Therefor when return is even not called, void has to be declared in the function docblock.

For example :

class Zend_Class

{

     /**

     * @return void

     */

     public function returnTheVoid ()

    {

         // Return nothing

     }

     /**

     * @return null

     */

     public function returnTheNull ()

    {

        return null ;

    }

}

复制代码

aqua_aqua

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Zend Framework 中的 Php 编码标准 (四) - 内嵌文档

原文： http://kbs.kimbs.cn/blog/list/post/26/title/zend-framework-coding-standards-for-php-inline-documentationZend Framework 中的 Php 编码标准 (四) - 内嵌文档1. Docblocks start always with "/*" or "
复制链接

扫一扫