网页制作过程中代码注释书写规范
点评:总结了一下自己工作中使用到的注释书写规范,没有什么技术含量,只是用于统一制作方式,方便维护。包含了“区域注释”、“单行注释”、“注释层级”和“协助注释”四个部分。大部分同学使用的区域注释的方法,会以“注释
总结了一下自己工作中使用到的注释书写规范,没有什么技术含量,只是用于统一制作方式,方便维护。包含了“区域注释”、“单行注释”、“注释层级”和“协助注释”四个部分。
大部分同学使用的区域注释的方法,会以“注释内容开始”或“注释内容结束”、“start”或“end”等,相比之下,以“S”或“E”开始可以更快的使用,比如只要写一次开始或结束的注释,然后复制,改下“S”或“E”就可以快速的完成区域的注释。
区域注释
在实际工作中,有时会出现分不清注释应该在标签之上还是标签之下,为了避免这种情况,注释信息统一写在区域标签开始之前和结束之后,并以“S”或“E”开始,表示区域注释的开始或结束。
例:
...
/*=S 注释内容*/
.class{
...
}
.class{
...
}
/*=E 注释内容*/
单行注释
注释信息应写在需注释的内容区域里
例:
...
.class{
/*注释内容*/
...
}
注释层级
在模块制作中,可能会出现区域中还有区域的情况,为了更好的区分区域之间的层级,引入
了注释层级的概念。
区域注释前面的等号表示了当前注释的层级
例:
...
...
...
...
...
/*=S 注释内容*/
...
/*==S 注释内容*/
...
/*===S 注释内容*/
...
/*===E 注释内容*/
...
/*==E 注释内容*/
...
/*=E 注释内容*/
协助注释
非作者维护时所加入的表示修改时间、修改人等标识信息。
在区域注释或单行注释的基础上加上修改人和修改时间等信息。例(区域注释):
...
/*=S 注释内容[修改人和修改时间]*/
.class{
...
}
.class{
...
}
/*=E 注释内容[修改人和修改时间]*/
例(单行注释):
...
.class{
/*注释内容[修改人和修改时间]*/ ...
}
Dreamweaver代码div+css Dreamweaver代码 基本结构标签: ,表示该文件为HTML文件
,包含文件的标题,使用的脚本,样式定义等,分段标志 ,采用黑体字 ,采用斜体字
属性是用来修饰标志的,属性放在开始标志内. 例:属性bgcolor="BLACK"表示背景色为黑色. 引用属性的例子:
表示页面背景色为黑色;程序代码注释编写规范 为提高控制程序的阅读性与可理解性,现制定相关代码程序代码注释编写的编写规范。 一般情况下,源程序有效注释量必须在20%以上,注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始,任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始,以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。 示例:下面这段头文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表,每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表,每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例:下面这段源文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************************ COPYRIGHT (C), MicTiVo International. Co., Ltd. FileName: Author:
C语言注释规范 1.注释原则 同一软件项目开发中,尽量保持代码注释规范和统一。 注释方便了代码的阅读和维护。 边写代码边注释,修改代码时要相应修改注释,保证注释和代码的一致性。 注释要简洁明确,不要出现形容词。 对于写的好的注释,我们将是第一个受益者。 大型软件开发中,通过别人的注释可以快速知道他人所写函数的功能,返回值,参数的使用。 2.文件头部的注释 示例: / * Program Assignment : 该文件的作用 * Author: 作者 * Date: 2013/8/6 14:34 * Description: 该文件的描述 *****/ /* * Source code in : 源代码的路径 * Function List: * initLinear 初始化线性表 * destoryLinear 释放线性表申请的空间 * isLinearEmpty 判断线性表是否为空 * isLinearFull 判断线性表是否为满 * getLinearElementValue 取得下标为index的元素的值 */ 注意:这个函数列表可以快速查询到我们想要了解的函数。 3.结构体,全局变量等的注释 示例: typedef POLYNOMIAL USER_TYPE; /* 新的数据类型的描述*/ int a; /* 全局变量的作用*/ /* 说明结构体的功能*/ typedef struct LINEAR { USER_TYPE *data; /* 每个成员的意义(作用) */ int maxRoom; /* 每个成员的意义(作用) */
int elementCount; /* 每个成员的意义(作用) */ }LINEAR; 4.函数的注释 在逻辑性较强的的地方加入注释,以便其他人的理解,在一定的程度上排除bug。 示例: /* * Function Name: getLinearElementIndex * Purpose: 取得元素的index值 * Params : * @LINEAR linear 线性表实例 * @USER_TYPE var 类型为USER_TYPE的实例 * @int (*)() cmp 提供接口,让用户定义具体比较函数 * Return: int 返回元素的index值 * Limitation: 如果返回-1,则代表不存在var的元素 */ int getLinearElementIndex(LINEAR linear, USER_TYPE var, int (*cmp)()) { /* * 如果逻辑太过复杂,这里写明该算法的过程和思路。 */ boolean found = FALSE; int i; for(i = 0; i < && !found; i++) if(cmp[i], var) == 0) found = TRUE; if(i >= i = NOT_FOUND; return i; }
Dreamweaver 8 基础代码 HTML基本结构(每个网页都是在基本结构的基础上添加内容的) ---------网页文件开始标签
--------头部元素开始标签1 Java 编程规范 1.1 排版 1.1.1 规则 规则1程序块要采用缩进风格编写,缩进的空格数为4个,不允许使用TAB缩进。(1.42+) 说明:缩进使程序更易阅读,使用空格缩进可以适应不同操作系统与不同开发工具。 规则2分界符(如大括号…{?和…}?)应各独占一行,同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序 或者static、,synchronized等语句块中都要采用如上的缩进方式。(1.42+) 示例: if (a>b) { doStart(); } 规则3较长的语句、表达式或参数(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐, 语句可读。(1.42+) 示例: if (logger.isDebugEnabled()) { logger.debug("Session destroyed,call-id" + event.getSession().getCallId()); } 规则4不允许把多个短语句写在一行中,即一行只写一条语句(1.42+) 说明:阅读代码更加清晰 示例:如下例子不符合规范。 Object o = new Object(); Object b = null; 规则5if, for, do, while, case, switch, default 等语句自占一行,且if, for, do, while,switch等语句的执行语句无论多少都要加括号{},case 的执行语句中如果定义变量必须加括号{}。 (1.42+) 说明:阅读代码更加清晰,减少错误产生 示例: if (a>b) { doStart(); }
2.2.3 字型设置标记 功能:设置文字的风格,如黑体、斜体、带下划线等,这是一组标记,它们可以单独使用,也可以混合使用产生复合修饰效果。常用的标记有以下一些: … :文字以粗体显示。 … :文字显示为斜体。 … :显示下划线。 … :删除线。 … :使文字大小相对于前面的文字增大一级。 … :使文字大小相对于前面的文字减小一级。 … :使文字成为前一个字符的上标。 …:使文字成为前一个字符的下标。 :使文字显示为闪烁效果。 …:以等宽体显示西文字符。 …:输出引用方式的字体,通常是斜体。 …:强调文字,通常用斜体加黑体。 …:特别强调的文字,通常也是斜体加黑体。 注:有些标记的效果必须在动态环境下才能显示,例如
程序编写规范及约定 (仅供内部使用) 文档作者:_______________ 日期:___/___/___ 开发/测试经理:_______________ 日期:___/___/___ 项目经理:_______________ 日期:___/___/___ 请在这里输入公司名称 版权所有不得复制
目录 程序编写规范及约定 (3) 1编写目的 (3) 2代码编写风格 (3) 2.1单元风格 (3) 2.2语句风格 (3) 3命名规则 (3) 3.1命名约定 (3) 3.1.1标志符 (3) 3.1.2类class (3) 3.1.3枚举类型enum (4) 3.1.4委托delegate (4) 3.1.5常量const (4) 3.1.6接口interface (4) 3.1.7方法function (4) 3.1.8命名空间namespace (4) 3.1.9参数 (4) 3.1.10局部变量 (5) 3.1.11数据成员 (5) 3.1.12自定义异常类 (5) 3.1.13命名缩写 (5) 3.1.14数据库命名 (5) 3.2代码编写命名规范 (6) 3.3界面常用控件命名约定 (6) 3.4文件命名规范 (7) 3.4.1文档文件命名 (7) 3.4.2配置文件命名 (7) 3.4.3程序文件命名 (7)
程序编写规范及约定 1编写目的 为了使编写代码具有可读性、可理解性、可维护性,对程序编写人员代码实行统一风格,使得程序代码能够以名称反映含义、以形式反映结构。此文档可供程序代码编写人员及代码维护人员使用。 2代码编写风格 2.1单元风格 2.2语句风格 3命名规则 3.1命名约定 Pascal和Camel命名约定: 编程的命名方式主要有Pascal和Camel两种(Pascal:每个单词的首字母大写,例如ProductType;Camel:首个单词的首字母小写,其余单词的首字母大写,例如productType) 3.1.1标志符 规则:Pascal、Camel 实例与描述:例子说明 3.1.2类class 规则:Pascal 实例与描述:Application
百度文库- 让每个人平等地提升自我 1 程序代码注释编写规范 为提高控制程序的阅读性与可理解性,现制定相关代码程序代码注释编写的编写规范。 一般情况下,源程序有效注释量必须在20%以上,注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。 示例:下面这段头文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************* (C), MicTiVo International. Co., Ltd. 1.File : . History: Date: Author: Modification: 2. .. *************************************************/ 一、源文件头 源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例:下面这段源文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************************ (C), MicTiVo International. Co., Ltd. FileName: Author: Version : Date: : / /*receive _process() */ 意:与溢出中断写初值不同}
程序代码注释编写规范 XXX份公司
为提高控制程序的阅读性与可理解性,现制定相关代码程序代码注释编写的编写规范。 一般情况下,源程序有效注释量必须在20%以上,注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始,任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始,以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。 示例:下面这段头文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表,每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表,每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例:下面这段源文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************************
1、头文件包含Includes 2、私有类型定义 Private typedef 3、私有定义Private define 4、私有宏定义 Private macro 5、私有变量 Private variables 6、私有函数原型Private function prototypes 7、私有函数Private functions 8、私有函数前注释 /****************************************************************************** * * Function Name : FSMC_NOR_Init * Description : Configures the FSMC and GPIOs to interface with the NOR memory. * This function must be called before any write/read operation * on the NOR. * Input : None * Output : None * Return : None ******************************************************************************* / 9、程序块采用缩进风格编写,缩进空格为4。 10、相对独立的程序块之间、变量说明之后必须加空行; 11、较长的字符(>80字符)要分成多行书写,长表达式要在低优先级操作符划分新行,操作符放在新行之首,新行要恰当缩进,保持排版整齐; 12、循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首; 13、若函数或过程中的参数较长,则要进行适当的划分。 14、不允许把多个短语句写在一行中,即一行只写一条语句。 15、if、for、do、while、case、switch、default等语句自占一行,且if、for、 do、while等语句的执行语句部分无论多少都要加括号{}。 16、对齐只使用空格键,不使用TAB键; 17、 函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case 语句下的情况处理语句也要遵从语句缩进要求 18、 程序块的分界符(如C/C++语言的大括号‘{’和‘}’)应各独占一行并且位于同一 列,同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以 及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。 19、 在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或
目录 一.规范简介 1.1 目的 所有的程序开发手册都包含了各种规则。一些习惯自由程序人员可能对这些规则很不适应,但是在多个开发人员共同写作的情况下,这些规则是必需的。这不仅仅是为了开发效率来考虑,而且也是为了后期维护考虑。 本规范正是为培养规范设计和编程,养成良好的习惯,增强软件产品的稳定,健壮,可靠性;同时也为了提高软件的可读性,可以让程序员尽快而彻底地理解新的代码,使产品可维护性提高而制定的规范。 1.2 开发规范的重要性 (1)减少维护成本; 一个软件的生命周期中,80%的花费在于维护,另一方面,几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护,规范的编码减少人员变动带来的维护成本。 (2)改善软件的可读性 可以让程序员尽快而彻底地理解新的代码。在一个团队中,代码也容易在程序员之间共享。 (3)维护部门交付产品的规范形象。 二.具体规范 2.1 注释 注释是软件可读性的具体表现。程序注释量一般占程序编码量的20%,软件工程要求不少于20%。程序注释不能用抽象的语言,要精确表达出程序的处理说明。避免每行程序都使用注释,可以在一段程序的前面加一段注释,具有明确的处理逻辑。 注释必不可少,但也不应过多,不要被动得为写注释而写注释。
2.1.1 需要注释的部分 (1)文件头注释,文件创建及修改记录,版权归属,作者以及修订者,以及对文件的简短描述。 (2)类的目的(即类所完成的功能)、设置接口的目的以及应如何被使用。 (3)成员方法注释(对于设置与获取成员方法,在成员变量已有说明的情况下,可以不加注释;普通成员方法要求说明完成功能,参数含义以及返回值)。 (4)普通成员方法内部注释(控制结构、代码所起到的作用以及如此编写代码的原因,处理顺序等)。 (4)参数的含义以及其他任何约束或前提条件、字段或属性描述。而对于局部变量,如无特别意义的情况下则不加注释。 2.1.2 具体注释 (1)文件头注释 要求:遵循JavaDoc的规范,在每一个源文件的开头注明该文件的作用, 作简要说明, 并写上源文件的作者,版权信息编写日期。如果是修改别人编写的源文件,要在修改信息上注明修改者和修改日期。 例子: /** * @Title: 文件名 * @Copyright (C) 年份龙图软件 * @Description: 文件信息描述 * @Revision History: * @Revision 版本号日期作者. */ (2)类和接口的注释 要求:遵循JavaDoc的规范,在每一个类的开头注明该类的作用,作简要说明,并写上作者,编写日期。 例子: /** * @ClassName: 类(或接口)名 * @Description: Description of this class
程序注释规范说明 程序注释规范应包括以下三方面: 一、文件头部注释 在代码文件的头部进行注释,这样做的好处在于,我们能对代码文件做变更跟踪。在代码头部分标注出创始人、创始时间、修改人、修改时间、代码的功能,这在团队开发中必不可少,它们可以使后来维护/修改的同伴在遇到问题时,在第一时间知道他应该向谁去寻求帮助,并且知道这个文件经历了多少次迭代、经历了多少个程序员的开发和修改。 样本: /***************************************************** ** 作者:Liuchao ** 创始时间:2007-11-12 ** 修改人:Liuchao ** 修改时间:2007-11-12 ** 修改人:Liaochao ** 修改时间:2007-11-12 ** 描述: ** 主要用于产品信息的资料录入,… *****************************************************/ 二、函数、属性、类等注释 请使用///三斜线注释,这种注释是基于XML的,不仅能导出XML制作帮助文档,而且在各个函数、属性、类等的使用中,编辑环境会自动带出注释,方便你的开发。以protected,protected Internal,public声明的定义注释都建议以这样命名方法。 例如: ///
/// 用于从ERP系统中捞出产品信息的类 /// class ProductTypeCollector { … } 三、逻辑点注释 在我们认为逻辑性较强的地方加入注释,说明这段程序的逻辑是怎样的,以方便我们自己后来的理解以及其他人的理解,并且这样还可以在一定程度上排除BUG。在注释中写明我们的逻辑思想,对照程序,判断程序是否符合我们的初衷,如果不是,则我们应该仔细思考耀修改的是注释还是程序了… 四、变量注释 我们在认为重要的变量后加以注释,说明变量的含义,以方便我们自己后来的理解以及其他人的理解,并且这样还可以在一定程度上排除BUG.我们常用///三斜线注释。 /// 用于从ERP系统中捞出产品信息的类 class ProductTypeCollector { int STData;///
把如下代码加入
区域中: 后退前进 返回 查看源码 禁止查看源码 刷新按钮一 刷新按钮二 回首页按钮 弹出警告框 状态栏信息 背景色变换 打开新窗口 窗口最小化