zend framework 中的 php 编码标准 (四) - 内嵌文档...
时间：2010-08-11 来源：servyo
|
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] <?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: * 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 [email protected] so we can send you a copy immediately. * * @category Zend * @package __PACKAGENAME__ * @subpackage __SUBPACKAGENAME__ * @copyright Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. (http://www.zend.com) * @license http://framework.zend.com/license/new-bsd New BSD License * @version $Id: $ * @depreciated Since 0.0.1 */ [/php] 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 [email protected] 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 [email protected] 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 : [php] /** * 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. (http://www.zend.com) * @license http://framework.zend.com/license/new-bsd New BSD License * @depreciated Since 0.0.1 */ class Zend_Controller_Dispatcher extends Zend_Controller_Dispatcher_Class implements Zend_Controller_Dispatcher_Interface [/php] 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; } } |
相关阅读 更多 +
