Web 相关开发编程约定
Contents
前端开发脚本语言代码规范
@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
命名约定
- 建议依从各种主流语言的命名原则!
- 从前端 的特性强烈建议以下:
- 模块文件名应该与模块中主应用函式名一致;
- 全局变量名 应该有模块/文件名 作为前缀!
- 常量命名时全部采用大写;常量一定要附有说明,特别是全局性常量!避免“魔法数字”
- 所有函式的命名“谓语化”,以尽量以主谓短语构成
- 尽量保持命名习惯,不要随意变动
- 所有网站公共元素命名及设计应以元素的应用范畴,意义为主,而非特性;
- 使用适用于领域内的术语/缩写;
- 鼓励运用“隐喻”形象化具有共性的事务的命名!但是一定要公开发布词汇表!
基本原则
- 包|文件名 全部小写!
- 因为语言支持类的话,要进行引用,都是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 定义的文件, 可以直接自动链接去! _*/
模块、阶段性功能注释
重要功能 或 设置 详细说明
- e.g
/*_******************************************** SET THE VALUE BELOW TO THE DIRECTORY WHERE THIS FILE RESIDES ADODB_RootPath has been renamed ADODB_DIR ********************************************_*/
自由说明
- e.g
// 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 说明文档!
- 该目录的功能及其包含内容
- 一个对每一文件的在线说明(带有link),每一个说明通常还应该提取文件标头的一些属性名字。
- 包括设置、使用说明
- 指导人们如何连接相关资源:
- 源文件索引
- 在线文档
- 纸文档
- 设计文档
- 其他对读者有帮助的东西
目录约定
动态网站开发的目录约定
//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 (2004-12-24)