Web 相关开发编程约定

总结以往的开发经验,约定标准的开发代码习惯

前端开发脚本语言代码规范

@version 5.1  041224    MoinMoin Wiki 语法化,对比各种文档化工具进行考虑
@version 5.0  030729    Wiki 语法化,并重新考虑所有细节!
@version 4.0  030403    完全实现EP化个性使用原则!
@version 3.0  030102    upgrade base Doxygen
@version 2.1  021116    edit for group
@version 2.0  021114    create

@author  ZoomQuiet (L) 2002-2003 All rights reserved.

@brief  这是 Web Design 个人规范化说明文件!
@note   指导设计,开发的规范化;为 Doxygen文档化准备!
@note   自觉记录主要变动!
        并以 uName::date; note 方式签名!

Web Define Scheme

命名约定

基本原则

基本规范

[作用域]{返回型别}{对象型别}+Name

基本缩写

注释约定

预定义关键字

关键字             含义
--- Structural indicators ---

class           文件,类注解
page            页面 说明!
par                     function name()

param           参数名     参数说明
return          返回值(包括类型)
exception       异常;例外 说明
code            代码举要!
endcode

--- Section indicators ---

brief           摘要,表示类、属性、方法要做些什么或者什么含义。
author          作者
version         { version number }

note            注解;原理说明;
warning         警告
attention       注意,环境需要!

sa                      参考
bug             已知bugs
todo            { paragraph describing what is to be done }
                        修改记录(编号规则为“#”+作者名|信箱+"::"+日期+“-”+序号)
par                     自定义关键词;或是大间隔空行
li                      列表

test            测试方法!
deprecated      禁止,不赞成

模块的注释

/**_
@class file_action
        文件的主要功能说明
@brief
        详细描述 
@author Zoom.Quiet ([email protected])
@version 20020523.100
记录主要的修改点
        Zoomq::odbc_fetch_into()参数位置第二和第三个位置调换
@version 20020523.101
        John Johnson [email protected]
@todo   计划中将完善的要点说明
@bug    已知欠缺要点
@test   测试说明
@par    安装
使用自定义关键词,进一步其它说明!

@code           代码举要!
@endcode

@sa (参照)
直接使用 class 定义的文件, 可以直接自动链接去!

@note           注解;原理说明;
@attention      注意,环境需要!

_*/

方法注释

/**_
@page  _myFunc
@par functin _myFunc()
使用自定义关键词作为页面标题!

@brief
        功能描述
Different SQL databases used 
different methods to combine strings together.
 This function provides a wrapper.

@var   变量说明
@param 形参说明
@param s        variable number of string parameters
@param [defstr]         the value to hilite
@param [blank1stItem]   true to leave the 1st item in list empty
@param [multiple]               true for listbox, false for popup
@note  $db->Concat($str1,$str2);

@return the general type of the data:
    @li C for character < 200 chars
    @li B for BLOB (>= 200 chars)
    @li N for numeric floating point
    @li D for date
    @li T for timestamp
    @li L for logical/Boolean
    @li I for integer
@note           注解;原理说明;
@attention      注意,环境需要!
@sa (参照)
直接使用 class 定义的模块名, Doxygen 可以直接自动链接去!

_*/

其它说明

/**_
@page  _myFile
不能使用中文
@par functin _myFunc()
使用自定义关键词作为页面标题!
@brief
        关键词描述
@li     列表叙述!
@section sectionID 章节
@subsection subsectionID 小节
@ref subsectionID
        页内跳转链接!
@sa (参照)
直接使用 class 定义的文件, 可以直接自动链接去!
_*/

模块、阶段性功能注释

重要功能 或 设置 详细说明

自由说明

// the array of types of each column (C B I L M)
* 如果希望进入 Doxygen export 文档的

/// the array of types of each column (C B I L M)

大型注释

有时需要注释大段的测试代码,最简单的方法就是使用if (0)块:

function example() {
        great looking code

        if (0) {
                lots of code
                ...
                ..
                .
        }

        more code
}

你不能使用/**/,因为注释内部不能包含注释,而大段的程序中可以包含注释。

定义文件后缀意义

.php .asp .jsp ...

程序以及页面文件;

.lbi

库文件,复用性代码块!

.dwt .zpt .tmp ...

模板文件

.inc.* _inc.*

功能性程序包含文件

.txt .t2t(txt2tags结构文本) .stx(reST结构文本)

说明文档

readme.txt 内容约定

目录约定

反馈


-- ZoomQuiet (2004-12-24)

WebDesignStandard (last edited 2009-12-25 07:09:26 by localhost)