《[开发规范]编码排版、注释规范.pdf》由会员分享，可在线阅读，更多相关《[开发规范]编码排版、注释规范.pdf（9页珍藏版）》请在金锄头文库上搜索。
1、 软件开发规范 试行版 Version 1 0 编程语言开发规范 2004 6 3 1 排版 1 1 1 程序块要采用缩进风格编写 缩进的空格数为4个 要求 使用编辑器提供的tab 设置功能 设置为4 绝对不允许使用4 个空格字符 1 1 2 不允许把多个短语句写在一行中 即一行只写一条语句 示例 如下例子不符合规范 rect length 0 rect width 0 应如下书写 rect length 0 rect width 0 1 1 3 较长的语句 页宽 80 字符 要分成多行书写 长表达式要在低优先级操作符处划分新 行 操作符放在新行之首 划分出的新行要进行适当的缩进 使排版整齐
2、语句可读 示例 perm count msg head len NO7 TO STAT PERM COUNT LEN STAT SIZE PER FRAM sizeof UL act task table frame id STAT TASK CHECK NUMBER index occupied stat poi index occupied act task table taskno duration true or false SYS get sccp statistic state stat item report or not flag taskno MAX ACT TASK NUM
3、BER 1 1 4 if for do while case switch default等语句自占一行 且if for do while等语句的执行语句部分无论多少都要加括号 示例 如下例子不符合规范 if pUserCR null return 应如下书写 if pUserCR null return 1 1 5 函数或过程的开始 结构的定义及循环 判断等语句中的代码都要采用缩进风格 case 语句下的情况处理语句也要遵从语句缩进要求 1 1 6 程序块的分界符 如大括号 和 应各独占一行并且位于同一列 同时与引用 它们的语句左对齐 在函数体的开始 类的定义 结构的定义以及if for d
4、o while switch case 语句中的程序都要采用如上的缩进方式 示例 如下例子不符合规范 if program code void example fun void program code 应如下书写 for program code if program code void example fun void program code 2 注释 1 2 1 一般情况下 源程序有效注释量必须在20 以上 说明 注释的原则是有助于对程序的阅读理解 在该加的地方都加了 注释不宜太多也不 能太少 注释语言必须准确 易懂 简洁 1 2 2 文件头部应进行注释 注释必须列出 版权说明 版本号
5、 生成日期 作者 内容 功 能 修改日志等 示例 建议所有文件使用该格式 java 文件使用javadoc 要求的格式 Copyright C 1988 1999 YOEE Info Tech Co Ltd File name 文件名 Author Version Date 作者 版本及完成日期 Description 用于详细说明此程序文件完成的主要功能 与其他模块 或函数的接口 输出值 取值范围 含义及参数间的控 制 顺序 独立或依赖等关系 Others 其它内容的说明 History 修改历史记录列表 每条修改记录应包括修改日期 修改 者及修改内容简述 Date Author Modif
6、ication 1 2 1 2 3 函数头部应进行注释 列出 函数的目的 功能 输入参数 输出参数 返回值 调用 关系 函数 表 等 示例 建议所有文件使用该格式 java 文件使用javadoc 要求的格式 Description 函数功能 性能等的描述 Pre Conditions 前置条件 Param 输入参数说明 包括每个参数的作用 取值说明及参数间关系 Return 函数返回值的说明 Others 其它说明 1 2 4 边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的一致性 不再有 用的注释要删除 要求 每 8 行内 必须要有一条注释 1 2 5 注释的内容要清楚 明了
7、 含义准确 防止注释二义性 说明 错误的注释不但无益反而有害 2 6 避免在注释中使用缩写 特别是非常用缩写 说明 在使用缩写时或之前 应对缩写进行必要的说明 1 2 7 注释应与其描述的代码相近 对代码的注释应放在其上方或右方 对单条语句的注释 相邻位置 不可放在下面 如放于上方则需与其上面的代码用空行隔开 示例 如下例子不符合规范 例 1 get replicate sub system index and net indicator repssn ind ssn data index repssn index repssn ni ssn data index ni 例 2 repssn
8、ind ssn data index repssn index repssn ni ssn data index ni get replicate sub system index and net indicator 应如下书写 get replicate sub system index and net indicator repssn ind ssn data index repssn index repssn ni ssn data index ni 1 2 8 注释与所描述内容进行同样的缩排 说明 可使程序排版整齐 并方便注释的阅读与理解 示例 如下例子 排版不整齐 阅读稍感不方便 v
9、oid example fun void code one comments CodeBlock One code two comments CodeBlock Two 应改为如下布局 void example fun void code one comments CodeBlock One code two comments CodeBlock Two 1 2 9 将注释与其上面的代码用空行隔开 示例 如下例子 显得代码过于紧凑 code one comments program code one code two comments program code two 应如下书写 code o
10、ne comments program code one code two comments program code two 1 2 10 对变量的定义和分支语句 条件分支 循环语句等 必须编写注释 说明 这些语句往往是程序实现某一特定功能的关键 对于维护人员来说 良好的注释帮 助更好的理解程序 有时甚至优于看设计文档 示例 if 注释 else 注释 2 11 避免在一行代码或表达式的中间插入注释 说明 除非必要 不应在代码或表达中间插入注释 否则容易使代码可理解性变差 2 12 在程序块的结束行右方加注释标记 以表明某程序块的结束 说明 当代码段较长 特别是多重嵌套时 这样做可以使代码更
11、清晰 更便于阅读 示例 参见如下例子 if program code while index MAX INDEX program code end of while index MAX INDEX 指明该条 while语句结束 end of if 指明是哪条if语句结束 3 命名 1 3 1 JAVA 命名规范 Package 的命名 Package 的名字应该都是由一个小写单词 组成 Class 的命名 Class 的名字 必须由大写字母开头而其他字母都小写的单词组成 接口的命名 与类名命名方式一致 但在该类名的前面增减大写字母 I 表示接口的意思 方法的命名 方法名是一个动词 采用大小写混
12、合的方式 第一个单词的首字母小写 其后单词的 首字母大写 如 run runFast getBackground Class 变量的命名 变量的名字必须用一个小写字母开头 后面的单词用大写字母开头 变量名不应 以下 划线或美元符号开头 尽管这在语法上是允许的 变量名应简短且富于描述 变量名 的选用应该易于记忆 即 能够指出其用途 尽量避免单个字符的变量名 除非是一 次性的临时变量 临时变量通常被取名为i j k m 和n 它们一般用于整型 c d e 它们一般用于字符型 Static Final 变量的命名 Static Final 变量的名字 应该都大写 并且指出完整含义 参数的命名 参数的
13、名字必须和变量的命名规范一致 数组的命名 数组应该总是用下面的方式来命名 byte buffer 而不是 byte buffer 方法的参数 使用有意义的参数命名 如果可能的话 使用和要赋值的字段一样的名字 SetCounter int size this size size 1 3 2 页文件 文件夹命名及管理 命名原则 用代表其含义的英文单词 以及数字表示 不易翻译的用关键字拼音 字母要 统一用小写 不得含空格和特殊字符 下划线和破折号除外 最好不要超过8 个字符 管理原则 系统相关及目录 文件实行统一管理 个人不能随意创建和修改目录 原则上 相近的内容放在同一目录下 1 文件夹命名 根据
14、功能或文件类型定义文件夹 例如 css script images public prompt info 根据网站频道定义文件夹 例如 首页 homepage 我的行程 myjourney 2 文件命名 网页命名 文件名用代表其含义的英文单词 以及数字表示 不易翻译的用关键字拼音 首页以 default 命名 保存根目录下 被引用文件的命名 本身不是一个完整的网页 可被其它页面引用 被引入文件统一放在统一文件夹下 如 include 命名规则为 如果被引用文件被多个频道引用则 public 功能 ext例如 菜单 public menu inc 或 public menu js 如果被单个频道引用则 频道 功能 ext 例如 会员注册 member register inc 文件的存放 遵循 管理原则 另外 1 游易首页放在最外层文件夹 其它频道首页放在频道文件夹内 2 频道内的网页放在频道文件夹内 1 3 3 图片命名 如果图片只被某一个页面或被引用文件使用 命名规则为 网页名 图片编号 ext或被引用文件名 图片编号 ext 如果公用图片使用 命名规则为 public 图片编号 ext
