Zdeveloper2.x代码规范
1 ZDeveloper命名规范
常用JAVA包命名(以platform插件为例)。
2 公共包
plugins存放所有插件配置文件；
lang存放所有插件国际化配置文件；
JAVA存放所有插件java类文件；
DB目录存放zdm文件。
3 一般情况java包
*.ui子包存放本插件所属UI类(*.ui省略前面的com.zving.platform,下同)；
*.service子包存放本插件所属扩展服务类；
*.service.impl子包存放扩展服务项实现类；
*.extend子包存放本插件扩展相关的类（扩展点接口类或抽象类）；
*.extend.impl子包存放本插件扩展实现类（扩展行为或其他扩展实现类）；
*.bl子包存放本插件所属后台业务逻辑类。
4 特殊扩展服务用到java包
*.code子包存放本插件所属扩展代码管理扩展服务的扩展项类；
*.privilege子包存放本插件扩展菜单权限服务的扩展项类；
*.config子包存放本插件扩展配置项扩展服务的扩展项类；
*.properties子包存放本插件扩展栏目或站点配置项相关的扩展服务的扩展项类；*.tag子包存放本插件扩展标签服务的扩项类；
*.tempalte子包存放本插件扩展模板服务的扩展项类；
（插件包的命名参展以上方式，项目需要可以酌情添加有一定意义的子包）
5 插件包
插件包统一以”com.zving.”+插件名称来命名(公司名称域名+插件名称)。
6 插件类
插件名称+”Plugin”，位于插件所属包根目录下。
7 插件配置文件
“com.zving.”+插件名称+”.plugin”。
8 UI类
页面名称+”UI”，类存放位置为“com.zving.”+插件名称+”.ui”子包。
9 扩展服务类
服务名称+”Service”，类存放位置为“com.zving.”+插件名称+”.service”子包。
10 扩展项类
依据扩展服务类定义子类接口规则命名,如模板服务的扩展项以Template结尾，菜单权限扩展服务器的扩展项以Priv结尾等。
11 扩展点抽象类
扩展点ID，类存放位置为”com.zving”+”插件名称”+”.extend”子包。
12 扩展行为类
扩展点ID+”Action”，类存放位置为“com.zving.”+插件名称+”.extend.impl”子包。
13 ZDM文件
*.zdm文件统一放在DB目录下，通常每个插件对应唯一的一个ZDM文件，zdm文件以插件名称命名，首字母大写。
zdm中的表命名规则：
1）首字母大写；
2）通用前缀ZC***，例如：ZCContent，其中Z表示ZVING，C指代产品类型CMS，Content 表示具体的表实际描述名称。ZDUser，其中D表示Developer，指我们的基础开发平台。类似的还有ZShop中的ZSGoods等。
14 UI目录下文件命名规则
目录名称一律小写，页面文件名称首字母小写。
15 JAVA代码
Java代码应条理清晰易读，通常保持缩进规范适当空行即可，复杂的业务逻辑代码添加关键部分的注释说明。
16 总体原则
命名能有具体含义，不要是用简单字母组合、中文拼音以及不常见的单词缩写等。17 JAVA代码命名规范(摘自网络)
定义规范的目的是为了使项目的代码样式统一，使程序有良好的可读性。
包的命名（全部小写，由域名定义）：
Java包的名字都是由小写单词组成。但是由于Java面向对象编程的特性，每一名Java 程序员都可以编写属于自己的Java包，为了保障每个Java包命名的唯一性，在最新的Java 编程规范中，要求程序员在自己定义的包的名称之前加上唯一的前缀。由于互联网上的域名称是不会重复的，所以程序员一般采用自己在互联网上的域名称作为自己程序包的唯一前缀。
例如：net.frontfree.javagroup
类的命名（单词首字母大写）：
根据约定，Java类名通常以大写字母开头，如果类名称由多个单词组成，则每个单词的首字母均应为大写例如TestPage；如果类名称中包含单词缩写，则这个所写词的每个字母均应大写，如：XMLExample，还有一点命名技巧就是由于类是设计用来代表对象的，所以在命名类时应尽量选择名词。
例如：Graphics
方法的命名（首字母小写，字母开头大写）：
方法的名字的第一个单词应以小写字母作为开头，后面的单词则用大写字母开头。
例如：drawImage
常量的命名（全部大写，常加下划线）：
常量的名字应该都使用大写字母，并且指出该常量完整含义。如果一个常量名称由多个单词组成，则应该用下划线来分割这些单词。
例如：MAX_VALUE
18 参数的命名
参数的命名规范和方法的命名规范相同，而且为了避免阅读程序时造成迷惑，请在尽量保证参数名称为一个单词的情况下使参数的命名尽可能明确。
19 Javadoc注释
Java除了可以采用我们常见的注释方式之外，Java语言规范还定义了一种特殊的注释，也就是我们所说的Javadoc注释，它是用来记录我们代码中的API的。Javadoc注释是一种多行注释，以/**开头，而以*/结束，注释可以包含一些HTML标记符和专门的关键词。使用Javadoc注释的好处是编写的注释可以被自动转为在线文档，省去了单独编写程序文档的麻烦。
例如：
/**
*This is an example of
*Javadoc
*@author darchon
*@version 0.1, 10/11/2002
*/
在每个程序的开始部分，一般都用Javadoc注释对程序的总体描述及版权信息，然后在主程序中可以为每个类、接口、方法、字段添加Javadoc注释，每个注释的开头部分先用一句话概括该类、接口、方法、字段所完成的功能，这句话应单独占据一行以突出其概括作用，
在这句话后面可以跟随更加详细的描述段落。在描述性段落之后还可以跟随一些以Javadoc 注释标签开头的特殊段落，例如上面例子中的@auther和@version，这些段落将在生成文档中以特定方式显示。
20 变量的命名
主要的的命名规范有以下三种：
Camel标记法：首字母是小写的,接下来的单词都以大写字母开头；
Pascal标记法：首字母是大写的,接下来的单词都以大写字母开头；
匈牙利标记法：在以Pascal标记法的变量前附加小写序列说明该变量的类型。
在Java我们一般使用匈牙利标记法，基本结构为scope_typeVariableName，它使用1-3字符前缀来表示数据类型，3个字符的前缀必须小写，前缀后面是由表意性强的一个单词或多个单词组成的名字，而且每个单词的首写字母大写，其它字母小写，这样保证了对变量名能够进行正确的断句。例如，定义一个整形变量，用来记录文档数量：intDocCount，其中int表明数据类型，后面为表意的英文名，每个单词首字母大写。这样，在一个变量名就可以反映出变量类型和变量所存储的值的意义两方面内容，这使得代码语句可读性强、更加容易理解。byte、int、char、long、float、double、boolean和short。
数据类型/前缀(附)：
byte/b
char/c
short/sh
int/i
long/l
char/c
string/s
float/f
double/d
hashtable/h
[]/arr
List/lst
Vector/v
StringBuffer/sb
Boolean/b
Byte/bt
Map/map
Object/ob
对于在多个函数内都要使用的全局变量，在前面再增加“g_”。例如一个全局的字符串变量：g_strUserInfo
在变量命名时要注意以下几点：
●选择有意义的名字，注意每个单词首字母要大写；
●在一段函数中不使用同一个变量表示前后意义不同的两个数值；
●i、j、k等只作为小型循环的循环索引变量；
●避免用Flag来命名状态变量；
●用Is来命名逻辑变量，如：blnFileIsFound。通过这种给布尔变量肯定形式的命名方式，使得其它开发人员能够更为清楚的理解布尔变量所代表的意义；
●如果需要的话，在变量最后附加计算限定词，如：curSalesSum；
●命名不相包含，curSales和curSalesSum；
●static final变量(常量)的名字应该都大写，并且指出完整含义；
●如果需要对变量名进行缩写时，一定要注意整个代码中缩写规则的一致性。例如，如果在代码的某些区域中使用intCnt，而在另一些区域中又使用intCount，就会给代码增加不必要的复杂性。建议变量名中尽量不要出现缩写；
●通过在结尾处放置一个量词，就可创建更加统一的变量，它们更容易理解，也更容易搜索。例如，请使用strCustomerFirst和strCustomerLast，而不要使用strFirstCustomer和strLastCustomer。常用的量词后缀有：First（一组变量中的第一个）、Last（一组变量中的最后一个）、Next（一组变量中的下一个变量）、Prev（一组变量中的上一个）、Cur（一组变量中的当前变量）；
●为每个变量选择最佳的数据类型，这样即能减少对内存的需求量，加快代码的执行速度，又会降低出错的可能性。用于变量的数据类型可能会影响该变量进行计算所产生的结果。在这种情况下，编译器不会产生运行期错误，它只是迫使该值符合数据类型的要求。这类问题极难查找；
●尽量缩小变量的作用域。如果变量的作用域大于它应有的范围，变量可继续存在，并且在不再需要该变量后的很长时间内仍然占用资源。它们的主要问题是，任何类中的任何方法都能对它们进行修改，并且很难跟踪究竟是何处进行修改的。占用资源是作用域涉及的一个重要问题。对变量来说，尽量缩小作用域将会对应用程序的可靠性产生巨大的影响。
关于常量的命名方法，在JAVA代码中，无论什么时候，均提倡应用常量取代数字、固定字符串。也就是说，程序中除0、1以外，尽量不应该出现其他数字。常量可以集中在程序开始部分定义或者更宽的作用域内，名字应该都使用大写字母，并且指出该常量完整含义。如果一个常量名称由多个单词组成，则应该用下划线“_”来分割这些单词如：NUM_DAYS_IN_WEEK、MAX_VALUE。
.
程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在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; }
使用说明书模板 根据所需改写即可 远程抄表能源管理系统 使用说明书 XXXXXXXX XXXX 年XX 月 文档控制 修改记录 * 修改类型分为A一Added M—Mod辻ied D—Deleted 审阅人 存档 目录 1醞
1.1背景 1.2应用领域与使用对象 1.4参考资料 1.5术语与缩耳解释 2系统综述 2.1系统结构 2.2系统功能简介 2.3性能 2.4版权声明 3运行环境 3.1硕件设备要求 3.2支持软件 3.3数据结构 4系统操作说明 4.1安装与初始化 4.2子模块名称1 4.2. 1业务需求描述 4. 2. 2界面截屏以及界面字段解释 4. 2. 3操作说明 4. 3子模块名称2 4. 3. 1业务需求描述 4. 3. 2界面截屏以及界面字段解释 4.4出错处理和恢复 4. 3. 3操作说明
1概述
1?1背景 系统的开发背景和编写这个手册的U的。 1.2应用领域与使用对象 描述软件所能使用的领域以及使用对象等。 1.4参考资料 列出有关资料的作者、标题、编号、发表日期、岀版单位或资料来源，可包括 与该产品有关的已发表的资料 文档中所引用的资料，所采用的软件标准或规范或业务规则 列岀编写本说明书时查阅的Internet上杂志、专业著作、技术标准以及他们的网址 1?3术语与缩写解释 2系统综述 4.4出错处理和恢复
2.1系统结构 结合系统所具有的功能包括输入、处理和输出提供该软件的总体结构图表。 2.2系统功能简介 结合本软件的开发实际逐项地说明本软件所有具有各项功能。 2.3性能 给出一般情况下的运行性能指数等。 2.4版权声明 声明版权所有者以及盗版应承当的法律责任。 3运行环境 3.1硬件设备要求 列出本软件所要求的硬设备的最小配置，如： 1、处理器的型号、内存、硬盘容量； 2、所要求的外存储器、媒体、记录格式、设备的型号和台数、联机/脱机; 3、I/O设备（联机/脱机）； 4、数据传输设备和转换设备的型号、台数。 3. 2支持软件
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(); }
产品说明书及其编写 高中通用技术技术与设计1 一、教学设计思路 本节课通过学生自主讨论探究、从而发现问题，建构新的知识体系，能够运用新的知识技能解决实际生活中的问题，坚实把握“做中学”和“学中做”的思想，不断地逐步提高学生对通用技术的理解，培养学生自主分析问题的能力，提高学生获取并理解技术知识理论的能力，提高学生应用技术具体分析、解决问题的能力。 1、教材分析 本节课是《普通高中课程标准实验教科书通用技术必修1 技术与设计1》第八单元《技术产品的使用和保养》中第一节《产品说明书及其编写》。作为本单元的入门篇目，要求理解并掌握产品说明书的定义和作用，并准确掌握产品说明书的编写方法，理解产品说明书的一般结构、表述形式、写作要求。本节课是后续课程《技术产品的使用、维护和保养》的基础，如何将产品说明书的编写与实践生活相联系，让技术思想深入学生脑海，是本节课需要攻克的一个难题。 2、学情分析 学生通过学习前面的技术课程，已经具有了一定的技术素养，这就为学习本节课奠定了一些知识基础。学生具有一定的生活和学习基础，产品说明书在他们的生活中处处可见，但对于产品说明书的认识只浮于表面，不够清晰具体，更不理解产品说明书的编写需要注意什么问题。 教材中，开题案例为“说明书表述错误引发卡式炉爆炸”，许多学生没有使用过燃气罐，缺乏亲身实践经历。若只按照教材直接讲授，难以激发学生的积极性，不能调动学生学习兴趣。本节教学应从学生能够理解的身边实例出发，让学生自己分析理解，让产品说明书深入学生的脑海。因此，本节课以自行车车轮的组装为例展开教学，激发学生学习兴趣的同时，巧妙引入产品说明书的课题。 二、教学目标 1、知识与技能：了解产品说明书的定义、作用，了解产品说明书的编写方法，结合简单的案例，能够从技术的角度出发，分别从结构、形式、要求三个方面理解产品说明书的编写。 2、过程与方法：通过观察实物、动手探究等课堂活动，结合典型案例分析，感受所学知识与实际生活的密切关系，能够通过课程内容达到编写简单产品说明书的目的。 3、情感、态度与价值观：通过课堂活动，能够激发学生的学习热情，培养动脑思考问题的良好习惯和小组合作能力的提升。 三、教学重点、难点 教学重点：理解产品说明书的定义与作用，了解说明书的结构、形式及写作要求。 教学难点：结合课程教学内容，编写简单的产品说明书。 四、教学方式、方法 1、案例分析 结合教师、学生提供的案例和课本案例进行分析，通过案例分析，达到知识传授的目
产品使用说明书编写规定 1 本标准规定了产品使用说明书的基本要求和编写方法。 本标准适应于湖北京山轻工机械股份有限公司产品使用说明书的编写。 2 引用标准 下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。本标准出版 时，所示版本均为有效。所有标准都会被修订，使用本标准的各方应探讨使用下列 标准最新版本的可能性。 工业产品使用说明书总则 JB/T5995 工业产品使用说明书机电产品使用说明书编写规定 3 基本要求 号或不同的字体表示， 或用特殊符号或颜色来强调。 使用说明书必须按下列等级和 告用 语提醒用户： —“危险”表示对高度危险要警惕； 表示对中度危险要警惕； 注意”表示对轻度危险要关注； 使用说明书应明确给出产品用途和适应范围， 并根据产品的特点和需要给出主要结 构、性 能、型式、规格和正确吊运、安装、使用、操作、维修、保养等的方法，以 及保护操作者 和产品的安全措施。 使用说明书内容的表述要科学、合理、符合操作程序，易于用户快速理解掌握。 对于复杂的操作程序，应多采用图示、图表、和操作程序图进行说明。 使用说明书中的图、表应和正文印在一起，图、表应按顺序编写序 3.8 具有几种不同和独 立功能的产品的使用说明书， 应先介绍产品的基本的和通常的功 能，然后再介绍其他方面的功能。 3.9 使用说明书应尽可能设想用户可能遇到的问题，并提供预防和解决的办法。 3.10应使用简明的标题和标注，以帮助用户快速找到所需内容。 3.11使用说明书应将机、电、气、液等融合一起编制，不能各行其是。 3.12外购件的使用说明书应附在相应的产品使用说明书上。编制产品使用说明书时， 除在产品使用说明书中简述其使用、 操作方法外， 还应注明详见某 某使用说 明书。 3.13使用说明书中的符号、代号、术语、计量单位应符合最新发布的国家法令、法规和 有关标 准的规定，并保持前后一致。 3.1 3.2 3.3 3.4 当需要时必须编制产品使用说明书，使用说明书是交付产品的组成部分。 使用说明书的开本幅面采用 16开，大于 16开的幅面应折页成 16 开。多页应装订 成册。 使用说明书可按产品型号编制， 也可按产品系列编制。 复杂产品和成套设备可按功 能单元、整机分别编制使用说明书， 再按产品型号、 用途组合成系统的使用说明书。 使用说明 书应对涉及安全方面的内容给出安全警告。 安全警告的内容应用较大的字 “做小” 3.5 3.6 3.7
程序编写规范及约定 (仅供内部使用) 文档作者：_______________ 日期：___/___/___ 开发/测试经理：_______________ 日期：___/___/___ 项目经理：_______________ 日期：___/___/___ 请在这里输入公司名称 版权所有不得复制
目录 程序编写规范及约定 (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. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************
产品说明书的写法 作者:未知来自:百度贴吧点击: 12566 时间:2007-5-29 （一）产品说明书概述 产品说明书，是对商品的性能、用途、使用和保养方法以及注意事项等作书面介绍的文书。产品说明书，又叫商品说明书。产品说明书的作用：助和指导消费者正确地认识商品、使用和保养商品，兼具宣传商品的作用。根据内容和用途的不同：可分为民用产品说明书、专业产品说明书、技术说明书等。根据表达形式的不同：可分为条款式说明书、文字图表说明书等。根据传播方式的不同，可分为：包装式：即直接写在产品的外包装上。内装式：将产品说明书专门印制，甚至装订成册，装在包装箱（盒）内。 （二）产品说明书的特点 ⒈说明性。说明、介绍产品，是主要功能和目的。 ⒉实事求是性。必须客观、准确反映产品。 ⒊指导性。还包含指导消费者使用和维修产品的知识。 ⒋形式多样性。表达形式可以文字式，也可以图文兼备。 （三）产品说明书的结构和写法 ⒈标题。一般是由产品名称加上“说明书”三字构成，如《VCD说明书》。有些说明书侧重介绍使用方法，称为使用说明书，如《吹风机使用说明》。 ⒉正文。通常详细介绍产品的有关知识：产地、原料、功能、特点、原理、规格、使用方法、注意事项、维修保养等知识。不同说明书的内容侧重点也有所不同。一般的产品说明书分为⑴家用电器类。⑵日用生活品类。⑶食品药物类。⑷大型机器设备类。⑸设计说明书。 ⒊附文。厂名、地址、电话、电挂、电传、联系人和生产日期等。出口产品在外包装上写明生产日期、中外文对照。
（四）注意事项： 突出产品特点。要注意广告和说明书的区别。如“喝孔府家酒，做天下文章”可做广告语，写入产品说明书不合适。语言要求准确、通俗、简明。尽可能图文并重。 【案例】 香雪牌抗病毒口服液使用说明书 (纯中药新药) 本品系以板兰根、藿香、连翘、芦根、生地、郁金等中药为原料，用科学方法精心研制而成。是实施新药审批法以来通过的，第一个用于治疗病毒性疾患的纯中药新药。 本品经中山医科大学附属第一医院、第一军医大学南方医院和广州市第二人民医院等单位严格的临床证，证明对治疗上呼吸道炎、支气管炎、流行性出血性结膜炎(红眼病)、腮腺炎等病毒性疾患有显著疗效。总有效率达91．27％。其中，对流行性出血性结膜炎(红眼病)和经病毒分离阳性的上呼吸道炎疗效均为100％，并有明显缩短病程的作用。 本品疗效确切，服用安全、方便，尤其适用于儿童患者，是治疗病毒性疾病的理想药物。 [性状]本品为棕红色液体，味辛，微苦。 [功能与主治]抗病毒药。功效清热祛湿，凉血解毒，用于治疗风热感冒、瘟病发热及上呼吸道感染、流感、腮腺炎等病毒感染疾患。 [用法与用量]口服，一次10ml，一日2～3次，宜饭后服用，小儿酌减。 [注意事项]临床症状较重，病程较长或合并有细菌感染的患者应加服其他治疗药物。 [规格]每支10ml。
工业产品使用说明书的编写方法 一、编写工业产品使用说明书的基本要求 编写工业产品使用说明书应符合下列四个方面基本要求： 1．应明确具体规定产品的用途和使用方法 要根据产品的使用功能和特点，具体而明确地写明产品的用途和适用范围，同时写明主要结构、性能参数、型式和规格以及正确贮运、安装、使用（操作）、维修、保护等方法。 产品使用说明书可按产品型号编写，也可按产品系列编写。 2．涉及到安全、卫生和环境保护等方面要求必须写明 当产品具有危险和有害因素时，必须在产品使用说明书中写明保护产品和操作者的安全卫生措施，对易燃、易爆、有毒、有腐蚀性和有放射性的危险产品，更应在使用说明书上规定防范措施、注意事项以及发生意外时的紧急处理办法等内容。 对影响环境的产品，使用说明书上还应规定必要的保护环境方面的内容。此外，对一些耗能较大产品应说明节能措施。 3．复杂产品和成套设备应编写系统的使用说明书
对一些复杂产品和成套设备，可按其功能单元、整机分别编写使用说明书，再组合成一套系统的使用说明书。 4．简单产品可不写使用说明书 对一些冶金、矿产、建材等原材料类产品以及用于组装配套的一些元器件、零部件等简单产品，如其产品标准、产品手册、质量证明书等有关技术文件能满足用户需要时，可由这些技术文件代管产品使用说明书，不必另行编写产品使用说明书。 二、产品使用说明书的内容构成 一般工业产品使用说明书应包括下列内容： 1．产品概述 产品概述部分主要写明产品的用途，适用范围（必要时还应写明不适用范围），产品规格型号的含义，使用环境条件或工作条件等方面内容。 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本标准规定了产品使用说明书的基本要求和编写方法。 本标准适应于湖北京山轻工机械股份有限公司产品使用说明书的编写。 2引用标准 下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。本标准出版时，所示版本均为有效。所有标准都会被修订，使用本标准的各方应探讨使用下列标准最新版本的可能性。 GB9969.1 工业产品使用说明书总则 JB/T5995 工业产品使用说明书机电产品使用说明书编写规定 3基本要求 3.1当需要时必须编制产品使用说明书，使用说明书是交付产品的组成部分。 3.2使用说明书的开本幅面采用16开，大于16开的幅面应折页成16开。多页应装订 成册。 3.3使用说明书可按产品型号编制，也可按产品系列编制。复杂产品和成套设备可按功 能单元、整机分别编制使用说明书，再按产品型号、用途组合成系统的使用说明书。 3.4使用说明书应对涉及安全方面的内容给出安全警告。安全警告的内容应用较大的字 号或不同的字体表示，或用特殊符号或颜色来强调。使用说明书必须按下列等级和警告用语提醒用户： —“危险”表示对高度危险要警惕； —“警告”表示对中度危险要警惕； —“注意”表示对轻度危险要关注； 3.5使用说明书应明确给出产品用途和适应范围，并根据产品的特点和需要给出主要结 构、性能、型式、规格和正确吊运、安装、使用、操作、维修、保养等的方法，以及保护操作者和产品的安全措施。 3.6使用说明书内容的表述要科学、合理、符合操作程序，易于用户快速理解掌握。3.7对于复杂的操作程序，应多采用图示、图表、和操作程序图进行说明。 使用说明书中的图、表应和正文印在一起，图、表应按顺序编写序号。 3.8具有几种不同和独立功能的产品的使用说明书，应先介绍产品的基本的和通常的功 能，然后再介绍其他方面的功能。 3.9使用说明书应尽可能设想用户可能遇到的问题，并提供预防和解决的办法。 3.10应使用简明的标题和标注，以帮助用户快速找到所需内容。 3.11使用说明书应将机、电、气、液等融合一起编制，不能各行其是。 3.12外购件的使用说明书应附在相应的产品使用说明书上。编制产品使用说明书时，除 在产品使用说明书中简述其使用、操作方法外，还应注明详见某某使用说明书。 3.13使用说明书中的符号、代号、术语、计量单位应符合最新发布的国家法令、法规和 有关标准的规定，并保持前后一致。 3.14当产品结构、性能等改动时，使用说明书的有关内容必须按规定程序、及时作相应 修改。 4基本内容 4.1封面 封面一般应包括：产品型号、名称、使用说明书字样。 4.2次页
目录 一．规范简介 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;///
工业产品使用说明书标准 工业产品使用说明书总则 1 基本要求 1.1 使用说明书是交付产品的组成部分. .使用说明书应明确给出产品用途和适用范围,并根据产品的特点和需要给出主要结构,性能参数,型式与规格和正确吊运. 安装.使用.操作.维修.保养 和贮存等方法,以及保护操作者和产品的安全措施. .对影响环境和能源的产品,使用说明书还应规定必要的保护环境和节约能源方面的内容 .对易烧.易爆,有毒.有腐蚀性,有放射性等产品.还应包括防护措施. 注意事 项和发生意外时的紧急处理办法等内容. 1.2 当产品结构,.性能等有改动而影响使用时,使用说明书的有关内容必须
作相应修改. 1.3 使用说明书可按产品型编制,也可按产品系列, 成套性编制.按系列.成套性编制时,其内容和参数不同之部分必须明显区分. .复杂产品和成套设备可按功能单元.整机分别编制使用说明书, 再按产品型号,用途组合成系统的使用说明书. 1.4 冶金.矿产,建材等原材料类产品及用于主机厂配套的元器件等产品,如质量证明书. 产品标准.产品手册等技术文件能满足用户需要时,则可用其代替使用说明书. 2 一般规定 2.1 使用说明书的印制 .使用说明书应能长期使用,保证在产品预期寿命期内的可用性.(批量定型产
品的使用说明书.一般应采用铅印).使用说明书的文字,符号,图示.表格,照 片等应清晰.整齐.双面印制者,不得因透背等原因而影响阅视. 2.2 使用说明书的文本 .使用说明书的开本幅面,一般应附合下列规定. a.铅印本:64开(92mm*12mm) 32开(130mm*184mm) 16开(188mm*260mm) 必要时采用其他幅面尺寸,但应符合GB788的规定. b.晒印本:A4号图纸(210mm*297mm)表格. 图形等允许向横向加长.确属必要时方可向纵向加长.数量多的大幅面附图. 附表可分装 .使用说明书根据内容多少可为单页.折页和多页.多页应装订成册. .供给国内用户的工业产品必须有汉文使用说明书, 出品工业产品一般应编
在软件开发的过程中总是强调注释的规范，但是没有一个具体的标准进行说明，通常都是在代码编写规范中简单的描述几句，不能作为一个代码注释检查的标准和依据，做什么都要有一个依据吗:),现在我特整理了一个《Java的注释规范》，内容来自网络、书籍和自己的实际积累。 JA V A注释规范 版本/状态作者版本日期 1.0 ghc 2008-07-02 一、背景 1、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分析这段代码，我们需要什么样的注释信息？ 2、怎么样避免我们的注释冗长而且凌乱不堪呢？ 3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？ 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本, 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。 三、注释的原则 1、注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。 2、注释的简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 3、注释的一致性 在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。 4、注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。 5、注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。 6、删除无用注释
骨科常见无源植入类产品说明书编写规范 （征求意见稿） 本编写规范旨在规范常见骨科无源植入类产品说明书的格式和内容，指导说明书的编写。同时规范注册申报和技术审评工作，为医疗器械注册管理部门的技术审评人员提供说明书审核的参考内容，从而降低资料发补率，统一审评尺度，提高审评效率。最终力求上市说明书格式清晰、用语准确，确保使用者和操作者能够从产品说明书中获得清晰、准确的信息，确保产品临床使用的安全有效。 本编写规范的编写参考了国内已上市的、具有代表性的国产及进口骨科无源植入类产品的说明书，但说明书内容应首先符合国家食品药品监督管理总局《医疗器械说明书、标签和包装标识管理规定》的有关要求。 本编写规范中的说明书参考格式系对常见骨科无源植入类产品说明书中主流和典型的说明书特征的归纳总结，涵盖了关节（附件1—附件8）、脊柱（附件9—附件23）、创伤（附件24—附件52）、骨填充物（附件52+）等相关产品的说明书。参考格式均包括但不限于如下标题项：医疗器械注册证书编号；产品技术要求编号；医疗器械生产许可证编号；产品名称；产品性能、结构及组成；型号、规格；适用范围；禁忌症；并发症；注意事项；警示；安装使用说明及图示；储存条件；有效期限；制造商名称；制造商注册地址
；生产地址；售后服务机构；代理人的名称、地址及联系方式；标签所用的图形、符号、缩写等内容的解释；其他。申请人/制造商应依据所申报产品的具体特性和支持性资料确定参考格式中具体内容（除标题项名称“【】”中的内容）是否适用，并对适用的内容进行充实和细化(包括增加标题项)，对不适用的内容进行修改和删除，确保说明书内容与申报资料相一致。说明书至少应包括标题项所规定的内容项目，制定说明书前请仔细阅读各标题项后“注”的内容。各类产品的具体参考格式详见附件。 本编写规范中通用的标题项及其注解如下： 【医疗器械注册证书编号】 注：取得医疗器械产品注册证后填写。 【产品技术要求编号】 注：取得医疗器械产品技术要求编号后填写。 【医疗器械生产许可证编号】 注：境内产品适用。 【产品名称】 注：产品名称应能体现产品技术结构特征和功能属性，属于体现产品性能结构及组成的描述性词语应在说明书的内容中予以体现。产品名称的命名应与已发布的国家标准、行业标准、医疗器械产品分类目录以及其他发布的规范中的产品名称保持一致。若产品能明确其所属注册单元，则产品名称