Differences between revisions 1 and 2

Web 相关开发编程约定

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

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

@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

命名约定

建议依从各种主流语言的命名原则！
从前端的特性强烈建议以下:
1. 模块文件名应该与模块中主应用函式名一致；
2. 全局变量名应该有模块/文件名作为前缀！
3. 常量命名时全部采用大写;常量一定要附有说明，特别是全局性常量！避免“魔法数字”
4. 所有函式的命名“谓语化”,以尽量以主谓短语构成
5. 尽量保持命名习惯,不要随意变动
6. 所有网站公共元素命名及设计应以元素的应用范畴,意义为主，而非特性;
7. 使用适用于领域内的术语/缩写;
8. 鼓励运用“隐喻”形象化具有共性的事务的命名！但是一定要公开发布词汇表！

基本原则

包|文件名全部小写！
- 因为语言支持类的话，要进行引用，都是URL 方式的，有的系统环境认大小写！那未，包，文件使用大小写不利于跨平台支持！
类名采用“Pascal格式”,即 WikiName 格式！由首字母大写单词组成！
函式名使用小写开头的 “Pascal格式”,以便与类区分
变量全部小写，
- 除非是特殊的变量！比如说:资源变量
常量全部大写！

基本规范

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

通用的统一命名全格式约定，可以根据具体情况加以删节；

基本缩写

/DevZipName --- 开发命名缩写词汇表!

注释约定

// 约定代码的注释风格！

预定义关键字

遵从Doxygen 语法;
实际使用时，注释关键字可以由"\"或是"@"引导，并以空格，间隔具体内容！

关键字             含义
--- 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 定义的文件， 可以直接自动链接去！
_*/

模块、阶段性功能注释

重要功能或设置详细说明

/*_********************************************
    SET THE VALUE BELOW TO THE DIRECTORY WHERE THIS FILE RESIDES
    ADODB_RootPath has been renamed ADODB_DIR
********************************************_*/

自由说明

// 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)来注释外部代码块

有时需要注释大段的测试代码，最简单的方法就是使用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 内容约定

作为注释的补充说明，应该在目录中安置 readme.txt 说明文档！
1. 该目录的功能及其包含内容
2. 一个对每一文件的在线说明（带有link），每一个说明通常还应该提取文件标头的一些属性名字。
3. 包括设置、使用说明
4. 指导人们如何连接相关资源：
  1. 源文件索引
  2. 在线文档
  3. 纸文档
  4. 设计文档
5. 其他对读者有帮助的东西

目录约定

动态网站开发的目录约定

//Zoomq::021114
        定义站点开发的目录意义:
        <建议关键功能性目录都有内容说明文档 _readme.zda>

/ 根目录,仅仅存放index 文件!
        /_stuff      杂物存放处, 可以利用为测试程序安放处
        /_Veles    所有可视化为己有元素的存放
                /Css
                /Fla      falsh原文件, 以及swf 动画
                /Frieworks    FW 设计原文件, 利于大家设计共享 ,正式发布站点时会去除!
                /Pics          真正使用的图片文件, 建议根据应用分目录存放, 并注意命名的规范化!最好有目录说明文档 _readme.zda
        /contents      静态内容页面的存放处, 初期的页面设计稿亦于此
        /Dload        存放供下载的工具包,比如说 falsh 的播放插件
        /Library        存放复用程度高的程序组件
                /nav
                /devGroupName   库定义文档则依照JAVA 类库的目录组织方式！使用目录路径进行名称空间区分！
                        /db
                        /login
                        /....
        /Templates   存放动态页面的模板
        /upLoad       存放客户上传的文件!

反馈

//Zoomq::021114

* //Zoomq::021120

edit .inc define

-- ZoomQuiet (Date(2004-12-24T03:55:07Z))

-  ⇤ ← Revision 1 as of 2004-12-27 09:02:33 → 
  Size: 8421
  Editor: ZoomQuiet
  Comment:
+   ← Revision 2 as of 2004-12-27 09:03:32 → ⇥
  Size: 8423
  Editor: ZoomQuiet
  Comment: 总结以往的开发经验，约定标准的开发代码习惯
-Deletions are marked like this.
+Additions are marked like this.
 Line 2:
-'''Web 相关开发编程约定'''
+'''Web 相关开发编程约定
'''
-Line 5:
+Line 6:
-''总结以往的开发经验，约定惯用的开发代码习惯''
+''总结以往的开发经验，约定标准的开发代码习惯''

Diff for "WebDesignStandard"