Joomla!开发代码书写规范 【转】

 

在一个开发项目中，代码书写规范是非常重要的，特别是对于开发人员较多的项目。好的代码书写规范能确保高质量，减少BUG，并且容易维护。

接下来，我们谈谈Joomla! 开发过程中的代码书写规范 Coding Standards

缩进与行最大长度

1、采用tab缩进，每个tab四个空格宽度。
2、行最大长度在75-85字符之间，这并不是硬性的规定，你可以根据自己的需要设置。

控制结构

代码控制结构语句包括 if, for, while, switch等语句，下面是一个if语句声明：

<?php if ((condition1) || (condition2)) { action1(); } elseif ((condition3) && (condition4)) { action2(); } else { // Use one true brace in control structures // when the block is longer than one line defaultaction(); anotheraction(); } ?> 

 

3、结构控制语句关键词与条件之间采用一个空格分开，从而跟函数调用区分。
4、强烈推荐即使在不必书写大，小括号的情况下，也不要忘记，这样使代码容易阅读，不容易出现逻辑错误。

下面是switch语句的示例：

<?php switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; } ?> 

 

 

函数调用

函数调用在函数名称与小括号之间没有空格，而在左括号与第一个参数之间留一个空格位置，逗号与每个参数之间有一个空格，最后一个参数与右括号之间有一个空格，右括号与分号之间没有空格。以下是样例：

<?php $var = foo( $bar, $baz, $quux ); ?>  

如上所示，在等号的两边应该各有一个空格，可以适当的在等号左边加tab，保证对齐美观。如下所示：

<?php
$short         = foo( $bar );
$long_variable = foo( $baz );
?>  

函数定义

类和函数定义遵循 "one true brace" 规范:

<?php function fooFunction( $arg1, $arg2 = '' ) { if (condition) { statement; } return $val; } class fooClass { function fooMethod( $arg1 ) { if ($arg) { $result = true; } else { $result = false; } return $result; } } ?>  

 

有默认值的参数在参数列表的尾部，要返回有意义的结果。以下是一个更长的例子：

<?php function connect( &$dsn, $persistent = false ) { if (is_array($dsn)) { $dsninfo = &$dsn; } else { $dsninfo = DB::parseDSN($dsn); } if (!$dsninfo || !$dsninfo['phptype']) { return $this->raiseError(); } return true; } ?> 

注释

要归档的注释应该遵循PHPDoc规范，更详细的内容请查看http://www.phpdoc.org/ 
推荐一定写非归档注释，在你还明白代码是如何运行和执行什么功能之前，请做好注释。
C风格注释(/* */)  和C++风格(/ /)都可以，不鼓励使用perl风格注释(#)

Including Code

有条件引入的情况下使用require_once()，无条件引入使用include_once()，从而确保只引入一次类文件。
注意：include_once() 与 require_once()都是声明，而不是函数，可以不必用括号包含文件名。

PHP Code Tags

采用<?php ?>包含php代码，而不是<? ?>
对于只有php代码的文件，结束的 (?>)标记是不必的，这样做可以避免意外的给页面输出加多空格。

 

 

SQL 查询

15、SQL关键词应该大些，其他的应该小写，不使用回车，可是为了可读性可以合理使用缩进。(这点在Joomla!的代码中遵循的非常好，我看过的源代码中，Joomla! core的这部分是最为规范的，译者)
16、查询应该单引号包含，PHP解析单引号包含的文本更快(以前很少注意这个方面，Joomla!够深入)。
17、所有quoted字串应该用quoted 函数处理，从而兼容不同的数据库。
18、所有的整数，浮点应该做转换处理 (int), (float) or (double)

$state = 1; $name = 'bill'; $db = &JFactory::getDBO(); $query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'. ' FROM jos_content AS c'. ' LEFT JOIN jos_users AS u ON u.id = c.created_by'. ' WHERE c.state = '.(int) $state ' AND u.id IS NOT NULL'. ' AND u.username <> '.$db->Quote( $name ). ' GROUP BY u.id'. ' HAVING COUNT( c.id ) > 0'; $db->setQuery(); // Output formated query: if ($debug) { echo $db->getQuery(); } $stats = $db->loadObjectList(); 

 

文件头部的注释块

19、所有的源代码文件应该包含下面的头部注释区域：

<?php   /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */   /**  * Short description for file  *  * Long description for file (if any)...  *  * PHP versions 4 and 5  *  * LICENSE: This source file is subject to version 3.0 of the PHP license  * that is available through the world-wide-web at the following URI:  * http://www.php.net/license/3_0.txt.  If you did not receive a copy of  * the PHP License and are unable to obtain it through the web, please  * send a note to 
 license@php.net so we can mail you a copy immediately.  *  * @category   CategoryName  * @package    PackageName  * @author     Original Author <
 author@example.com>  * @author     Another Author <
 another@example.com>  * @copyright  1997-2005 The PHP Group  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0  * @version    CVS: $Id:$  * @link       http://pear.php.net/package/PackageName  * @see        NetOther, Net_Sample::Net_Sample()  * @since      File available since Release 1.2.0  * @deprecated File deprecated in Release 2.0.0  */   /*  * Place includes, constant defines and $_GLOBAL settings here.  * Make sure they have appropriate docblocks to avoid phpDocumentor  * construing they are documented by the page-level docblock.  */   /**  * Short description for class  *  * Long description for class (if any)...  *  * @category   CategoryName  * @package    PackageName  * @author     Original Author <
 author@example.com>  * @author     Another Author <
 another@example.com>  * @copyright  1997-2005 The PHP Group  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0  * @version    Release: @package_version@  * @link       http://pear.php.net/package/PackageName  * @see        NetOther, Net_Sample::Net_Sample()  * @since      Class available since Release 1.2.0  * @deprecated Class deprecated in Release 2.0.0  */ class foo { }   ?>
 

20、没有硬性规定新的开发人员是否应该在作者列表中增加，通常来说改动量在10%-20%以上一半会添加作者列表。当然如果是功能重写或者新的逻辑关系则要添加作者。
21、简单的代码重构或者BUG修复就不必添加作者列表了。
22、U使用 "example.com", "example.org" and "example.net" 作为所有URLs and email addresses的示例。

 

 

 

命名空间

类

类应该具有描述性的名称，尽可能的避免抽象。类名称首字母应该大写。

函数与方法
函数与方法命名应该是"studly caps"风格(忘了怎么翻译了，应该是大小写混排方式)。通常函数应该有包名前缀，从而避免命名冲突，前缀后的第一个字母小写，以后名称中每个单词首字母大写。以下是例子：

connect()
 getData()
 buildSomeWidget()
 XML_RPC_serializeData() 

私有类成员(尽管PHP还不支持完全意义上的私有成员和函数)以下划线开头，以下是例子：

_sort()
 _initTree()
 $this->_status  

常量

常量应该总是大写的，单词之间用下划线连接，通常可以采用常量所在类或者包的名称大写做前缀，比如DB::包使用的前缀应该是DB_

全局变量

如果你的包要定义全局变量，全局变量应该以下划线开头，然后是包的名称大写，然后是变量名称，比如 $_PEAR_destructor_object_list.

Controllers

对于只有一个controller的组件，命名规范是[Name]Controller，而文件名称是controller.php.

<?php
/**
 * Content Controller
 * @package Joomla
 */
ContentController
{
    // Methods
}
?> 

对于有多个controller的组件，命名规范是[Component]Controller[Name].

<?php
/**
 * Banner Client Controller
 * @package Joomla
 */
BannerControllerClient
{
    // Methods
}
?>  

文件放在组件的/controllers/目录中，文件名反应controller的名字。

Single Controller
 
com_content
/- controller.php
 
Multi-controller
 
com_banner
/- controllers
  /- banner.php
  /- client.php 
 

Models
Models的命名规范是 [Component]Model[Name].

<?php
/**
 * Banner Client Model
 * @package Joomla
 */
BannerModelClient
{
    // Methods
}
?> 

文件放在组件的/models/目录下。

Views Layouts Templates Template Layout Overrides