澳客网开发编码约定

/ **

* 版权所有 (C) 2004 北京西线传媒科技有限公司

* 作者：刘振飞 liuzf@pku.org.cn; 王春生 wwccss@263.net

* 出品：北京西线传媒科技有限公司技术部 http://www.okooo.com

*

 * 这一程序是自由软件，你可以遵照自由软件基金会出版的GNU通用公共许可证条款来修

 * 改和重新发布这一程序。或者用许可证的第二版，或者 (根据你的选择)用任何更新的

 * 版本。

 *

 * 发布这一程序的目的是希望它有用，但没有任何担保。甚至没有适合特定目的的隐含的

 * 担保。更详细的情况请参阅GNU通用公共许可证。

 *

 * 你应该已经和程序一起收到一份GNU通用公共许可证的副本。如果还没有，写信给：

 *      The Free Software Foundation，Inc.，

 *      675 Mass Ave，

 *      Cambridge， MAO2139，USA

 * 还应加上如何和你保持联系的信息。

 *

 * 参考文档：http://www.w3cn.org/article/step/2004/26.html，对原作者表示感谢。

 *

 * 欢迎访问“西线传媒自由软件园地”：http://www.okooo.com/OpenSource/，我们会在这里陆续发布有用的自由软件。

 */

 

一、文件结构：

整个网站目录结构如下：(颜色示例：一级目录 二级目录 三级目录 四级目录)

/ 根目录（比如：/home/www/，可能会有所变化。）

|--- Documents(存放开发文档文件)

|--- Include(存放包含文件)

|--- Class（放置类定义文件，每一个类单独一个文件来定义。）

   |--- ClassFile1

   |--- ClassFile2

   |--- …………

 

|--- Config.inc.php  存储系统参数设置信息。

|--- Functions.inc.php  公用函数库文件。

|---- OtherFunction.inc.php 其他特定应用的函数库文件。根据实际情况命名。

|--- Setup.inc.php 参数变量初始化文件。其他的程序直接包含这个文件即可。

|--- Html

   |--- Images(存放网站图片文件，并根据栏目的名称建立相应的子目录。)

   |--- ChannelName1(存放ChannelName1栏目的图片文件)

       |--- ChannelName2

|--- CSS (存放网站样式表文件)

|--- Include (存放网页中需要包含的文件，比如JS教本等等。)

|--- ChannelName1 （存放ChannelName1栏目的程序文件。）

|----ChannelName2

|--- …………

|--- Admin(存放整个网站的管理程序。这个目录需要通过各种方法来加以保护。)

   |-- -Cache(Smarty模板生成的Cache文件，目录权限需要Other可写。)

   |--- Compile(Smarty模板生成的编译教本，目录权限需要Other可写。)

   |--- Smarty(存放Smarty类文件)

   |--- Pear(存放Pear类文件，可选。因为系统本身已有Pear.。)

   |--- Templats(存放Smarty模板文件，其目录结构与Html目录结构对应。)

   |--- Images(存放网站图片文件，并根据栏目的名称建立相应的子目录。)

   |--- ChannelName1(存放ChannelName1栏目的图片文件)

       |--- ChannelName2

|--- CSS (存放网站样式表文件)

|--- Include (存放网页中需要包含的文件，比如JS教本等等。)

|--- ChannelName1 （存放ChannelName1栏目的程序文件。）

|----ChannelName2

|--- …………

 

二、目录、文件命名约定：

目录、文件命名一律采用英文，，长度一般不超过20个字符，采用大小写结合的命名方式。除特殊情况才使用中文拼音。比如：Images,GetUserName.php ChangePassword.php

三、PHP脚本文件的组成部分：

每个文档按照以下顺序排列：文档说明部分、包含文件部分、变量声明、初始化部分、自定义函数部分和具体的语句。

3.1文档说明部分

在每一个文档的开头部分，要包含这个文档的编号，简要说明以及作者和最后修改时间。注释采用phpDocument的注释方式。

 

<?

/**

 * Okoo.com网站首页（简单注释）

 *

 * 此文件提供了网站所应用到的共用函数文件（详细说明）。

 * @file        $Source$

 * @package     Index（属于哪一个模块，可以根据程序的功能加以划分。）

 * @author      王春生 <wwccss@263.net>

 * @version     $Id$

 */

?>

 

如果页面是纯网页页面，则可以通过以下形式来说明：注意是以HTML的注释语句开始的。

<!--

/**

 * 网站首页（简单注释）

 *

 * 此文件提供了网站所应用到的共用函数文件（详细说明）。

 * @file        $Source$
 * @package     Index

 * @author      王春生<wwccss@263.net>

 * @version     $Id$

 */

-->

其中的$Id$在cvs checkout后会被cvs自动替换成文件基本信息，其中包含文件名、日期、修改者等cvs信息

 

3.2包含文件部分：

在每个文档的开头部分包含此文档所用到的包含文件。

比如：include(“Setup.inc.php”);

注：如果用到session则需要将session_start()函数放到文档的第一句。

3.3变量说明部分：

如果有变量需要特别声明，则在此给出。可以通过注释语句的方式来加以说明。比如：

//UserName 当前登陆用户的用户名。

3.4自定义函数部分：

如果当前PHP脚本需要定义一个函数，则在此声明。凡有两个以上文档用到的函数，则放到公共函数库文件里面，即/Include/Functions.inc.php文件中。

自定义函数需包含以下几个部分：函数功能描述、函数变量说明、返回值说明。

示例：

<?

/**

  * 数据库连接函数（简单说明）

  *

  * 通过这个函数链接到数据库，并返回相信的链接标识符。(详细的说明)

  * @author 王春生

  * @version 1.0

  * @global string             数据库服务器(全局变量声明,无需指定变量命，顺序对应)

  * @global string             数据库用户名

  * @global string             数据库密码

  * @global string             要使用的数据库

  * @param string $SQL        连接成功以后执行的查询语句，默认为空。（变量声明）

  * @return array              返回数据库连接信息。（返回值说明）

  */

  function dbConnect ($SQL="")

  {

    global $DbHost,$DbUser,$DbUserPWD,$DbDatabase; 

    $ConnInfo = array(); //存储连接信息

    $LinkID = mysql_connect($DbHost,$DbUser,$DbUserPWD);  //连接到数据库，返回连接ID

    mysql_select_db($DbDatabase);               //选择数据库

    $ResultID = mysql_query($SQL,$LinkID);      //返回查询结果ID

    $ConnInfo["LinkID"] = $LinkID;              //将两个ID存到数组$ConnInfo中

    $ConnInfo["ResultID"] = $ResultID;

    return $ConnInfo;                           //返回数组$ConnInfo

  }

?>

 

3.5文件结尾部分：

在所有文本文件(php、htm等)的最后必须写如下注释：

php:

<?

/**

 * $Log$

 */

?>

 

htm:

<!--

/**

 * $Log$

 */

-->

此注释在cvs checkout后会被cvs自动替换成文件修改记录。

四、程序注释约定：

文档和函数的说明采用phpdocument 的形式

模块说明采用句上注释的形式。每条语句的说明采用句左注释的方式。

文件声明与函数的注释请参照上面的格式。

下面是类文件的注释格式。

<?php

/**

 * 数据记录分页显示类。（对整个类文件的简单说明）

 *

 * 一个关于数据分页显示的类，可以通过下拉列表来选择页面。(详细的说明)

 * @package     Include  (所属的模块名称)

 * @author      王春生 <wwccss@263.net>

 * @version     $ID 2003-12-6 21:30 $

 */

  class Page

  {

    /**

     * 记录总数。（对类属性的声明。）

     * @var int

     */

     var $RecTotal;

 

    /**

     * 每页显示记录数。

     * @var int

     */

     var $RecPerPage;

 

/**

     * 取得某一条件查询结果的记录总数。(对类方法的说明,与对函数的说明相同)

   *

     * @global object $DB        数据库链接信息。

     */

     function GetRecTotal()

     {

    global $Mysql;

    …………

      }`

 

五、PHP语句书写格式约定：

if （$UserName = = “xxx” and $Password = = “xxx”）

{

   echo “你好”；

}

else

{

  echo “呵呵”;

}

 

大括号分成两列书写，理由是可以方便的界定大括号的范围。

缩进采用四个空格，不使用Tab键进行缩进。

函数名称与参数之间用空格格开。比如：$LinkID = mysql_connect( $UserName,$Host )

 

 

六、PHP变量的命名方式遵循下面几个原则：

(1)  大小写混合：采用大小写混合的形式来加以区分。比如：UserName

(2)  如果有单词缩写，则采用大写形式。如：SQL 。同时应该避免大写的单词在一起，比如IMGFile，无法直接判断单词的分割，则应该写成ImgFile。类的命名与变量命名类似，也采用大小写混合的方式。类的属性采用_开始，比如$Object->_Var1

 

七、PHP函数命名约定：

采用动词加名词的形式，动词小写，后面的名次用大小写间隔。如果需要，可以增加小写的前缀，这时动词则大写开始。比如：

没有前缀的情况：getUserName

有前缀的情况：sysGetUserName

八、数据库变字段命名约定：

(1)数据库、表、字段的命名与PHP变量命名相同，采用大小写混合的方式，比如：
Database:Okooo

Table :UserList

Field :UserName,UserPassword,BirthDate……     

（2）SQL 查询语句中关键词使用大写。 比如：SELECT * FROM UserList WHERE ……

（3）模块说明文档中如果有数据库的定义，请按照如下格式：

模块名称(如:用户表) 表名(如UserList)

表的说明：系统用户表

序号	字段名	字段描述	字段类型、大小	为空	默认值	键名	索引
1	ScholarID	学者编号	SmallInt Unsigned	Not	自增	Y	Y
2	ScholarName	学者姓名	VarChar(20)	Not		N	Y
3	SortID	排列顺序	TinyInt Unsigned	Not	1
4	ScholarIntro	学者简介	Text	Not		N	Y
5	Images	学者图片	VarChar(79)
6	AddUaser	添加者	VarChar(30)	Not
7	UpdateDate	最后更新时间	DateTime	0

备注：对某些字段的说明。或者自己的设计思想。

如果数据库后期有改动，文档上应随之改动，保持同步。

 

九、CVS操作约定：

(1)  文件前和文件后加上$Id$和$Log$ CVS tag，详见“三、PHP脚本文件的组成部分”部分。

(2)  CVS checkin的时候一定要写注释，注释的内容必须是此版本的修改信息，比如：

 + 增加用户名校验

 * 修正了密码bug

 - 去掉了abcde函数

详细说明如下：

1)     改动用符号标出来，“+”表示新增功能，“*”表示修改功能，“-”表示删除的功能；

2)     每个改动占一行；

3)     符号（“+”、“-”和“*”）前后各有一个空格。

 

十、XHTML代码规范

10.1 样式表的引用

样式表通过外部引用的方式调用，不建议在页面中新定义样式。

页面元素中的展现形式不建议通过html代码进行定义，都统一使用样式表进行。

比如要显示红色字体，用Html代码可以这样进行定义：

<font clolor=”red”>红色字体</font>

但最好的方法是通过样式表来定义。

<span class=”RedText”>红色字段</font>

这样可以将对网站样式的定义集中到一个样式表文件中去，如果对网站进行修改，可以很快进行。而如果分散到各个网页文件中去，改动起来就非常麻烦了。

10.2 缩进、换行约定

网页代码的缩进使用两个空格。

因为网页嵌套标签可能比较多，所以使用四个空格进行缩进会导致最深层的代码缩进太多，因而使用两个空格进行缩进。

如果一行中代码太长，请换行。

比如这样一行代码

<tr><td><input type=”text” name=”test” value=”test” class=”MyInput” οnclick=”alert(‘test’)”></td></tr>

可以改成

<tr>

<td>

<input type=”text” name=”test” value=”test” class=”MyInput” οnclick=”alert(‘test’)”>

</td>

</tr>

如果多行相似的代码出现，属性尽量对齐

比如

<input type="hidden" name="ProjectID"    value="{$ProjectID}">

<input type="hidden" name="ModuleID"    value="{$ModuleID}">

<input type="hidden" name="BugID"       value="{$BugID}">

<input type="hidden" name="AssignedTo"   value="{$AssignedTo}">

type、name和value属性对齐以后阅读起来比较方便。

对于某种标记的多个属性，其顺序尽量保持一致。

比如table标记的定义可以按照下面的顺序来定义。

<table width="90%" align="center" border="0" cellpadding="1" cellspacing="0" class="BgTable">

 

 

10.3 书写规范

10.3.1 所有的标记都必须要有一个相应的结束标记

 

       以前在HTML中，你可以打开许多标签，例如<p>和<li>而不一定写对应的</p>和</li>来关闭它们。但在XHTML中这是不合法的。XHTML要求有严谨的结构，所有标签必须关闭。如果是单独不成对的标签，在标签最后加一个"/"来关闭它。例如:<br /><img height="80" alt="网页设计师" src="../images/logo_w3cn_200x80.gif" width="200" />

 

10.3.2 所有标签的元素和属性的名字都必须使用小写

 

　　与HTML不一样，XHTML对大小写是敏感的，<title>和<TITLE>是不同的标签。XHTML要求所有的标签和属性的名字都必须使用小写。例如：<BODY>必须写成<body> 。大小写夹杂也是不被认可的，通常dreamweaver自动生成的属性名字"onMouseOver"也必须修改成"onmouseover"。

 

10.3.3 所有的标记都必须合理嵌套

 

10.3.4 所有的属性必须用引号""括起来

 

在HTML中，你可以不需要给属性值加引号，但是在XHTML中，它们必须被加引号。

 

10.3.5 给所有属性赋一个值

 

XHTML规定所有属性都必须有一个值，没有值的就重复本身。例如：

<td nowrap> <input type="checkbox" name="shirt" value="medium" checked>

　　必须修改为：

<td nowrap="nowrap">

<input type="checkbox" name="shirt" value="medium" checked="checked">

</td>

10.4 表单变量命名约定

       表单中的变量命名采用PHP的命名方式，使用大小写间隔。比如：

       <form name=”LoginForm”>

         <input type=”text”     name=”UserName”  value=””>

         <input type=”password” name=”Password”   value=””>

</form>

10.5 参考资料

网页设计师：http://www.w3cn.org/article/step/2004/26.html

十一、JavaScript 代码规范

11.1 目录文件结构

网站所有公用的JS脚本都放到Html/JS目录下面，按照类别进行命名，文件名沿用PHP文件的命名方式，采用大小写间隔的形式进行：比如FunctionsMain.js.

如果是第三方的脚本程序，则保持原来的命名不变。

11.2 变量命名约定

由于JavaScript区分大小写，所以对变量进行命名的时候需要谨慎。同时为了与php程序保持统一，JavaScript的变量命名也采用大小写间隔的形式。

如果JavaScript变量不参与与服务器的交互，（即此变量不向服务器进行传递）也可以在前面增加前缀，常见前缀见下表。

变量命名的标识符：

类型	前缀	举例
布尔型	bln	blnFinished
字节型	byt	bytLetter
日期型	dtm	dtmBirthday
双精度型	dbl	dblResult
错误信息	err	errBadInput
整型	int	intBeens
长整型	lng	lngDistance
对象	obj	objFirst
单精度整数	sng	sngBalance
字符串	str	strUserName

对象命名标识符

对象名称	前缀	举例
复选框	chk	chkToToMatch
列表框	lst	lstProvince
文本框	txt	txtUserName
按钮	btn	BtnVote

 

11.3 函数命名、注释约定

11.3.1 函数命名采用动词+名词的形式，第一项首字母小写。也可以增加前缀。

比如：function checkUserName()

增加前缀的命名可以为：function sysCheckUserName()

11.3.2 函数的注释沿用phpDoc的标准。

    比如：

/**  * Displays an confirmation box beforme to submit a "DROP/DELETE/ALTER" query.  * This function is called while clicking links  *  * @author                        wangcs<wwccss@263.net>  * @param   object   strLink       the link  * @param   object   strSqlQuery   the sql query to submit  * @return   boolean               whether to run the query or not  */ function confirmLink(strLink, strSqlQuery) { }

 

11.4 代码书写规范

11.4.1 缩进约定：缩进采用四个空格进行缩进。

11.4.2 每一行都以”;”结束。

11.4.3 循环、逻辑判断中大括号都单独占一行。

11.4.4 相邻几行代码中相似的部分尽量对齐。

比如：

/**  * 动态显示表格。  *  * @author                 王春生 <wwccss@263.net>  * @param  int ID           表格编号。  * @param  int TotalCount   表格总数。  */ function showTable(ID,TotalCount) {     for (I = 1; I <= TotalCount; I++)     {         if (I == ID)         {             document.all["Table" + I].style.display = "";         }         else         {             document.all["Table" + I].style.display = "none";         }     } }

11.5 参考资料

11.5.1 《看实例学习VBScript》

11.5.2 ．PhpMyAdmin中的JS脚本。

11.5.3 . TreeMenu中的JS脚本。

十二、修改记录

12.1 2004-2-18 修改记录：(ChangeLog)

1、  修改缩进为四个空格。

2、 增加数据库定义格式。

12.2 2004-3-11 修改记录：

 

3、  修改了PHP文档的组成部分，增加了CVS tag：$Id$和$Log$。

4、  增加了CVS操作约定。

12.3 2004-6-17 修改记录：

6.3类的属性采用下划线开始。

7           修改PHP函数命名的约定。

12.4 2004-11-16 修改记录：

将此文档的组织方式改为大纲方式。

增加XHTMl的代码规范。

增加JavaScript代码规范。