一, 规范存在的意义
应用编码规范对于软件本身和软件开发人员而言尤为重要, 有以下几个原因:
1, 好的编码规范可以尽可能的减少一个软件的维护成本 , 并且几乎没有任何一个软件, 在其整个生命周期中, 均由最初的开发人员来维护;
2, 好的编码规范可以改善软件的可读性, 可以让开发人员尽快而彻底地理解新的代码;
3, 好的编码规范可以最大限度的提高团队开发的合作效率;
4, 长期的规范性编码还可以让开发人员养成好的编码习惯, 甚至锻炼出更加严谨的思维;
二, 命名规范
1, 一般概念
1, 尽量使用完整的英文描述符
2, 采用适用于相关领域的术语
3, 采用大小写混合使名字可读
4, 尽量少用缩写, 但如果用了, 必须符合整个工程中的统一定义
5, 避免使用长的名字(小于 15 个字母为正常选择)
6, 避免使用类似的名字, 或者仅仅是大小写不同的名字
7, 避免使用下划线(除静态常量等)
2, 标识符类型说明
1, 包 (Package ) 的命名
Package 的名字应该采用完整的英文描述符, 都是由一个小写单词组成. 并且包名的前缀总是一个顶级域名, 通常是 com,edu,gov,mil.NET,org 等;
如: com.yjhmily.test
2, 类 ( Class ) 的命名
类名应该是个一名词, 采用大小写混合的方式, 每个单词的首字母大写. 尽量保证类名简洁而富于描述. 使用完整单词, 避免缩写词 ( 除非工程内有统一缩写规范或该缩写词被更广泛使用, 像 URL , html)
如: FileDescription
3, 接口 ( Interface ) 的命名
基本与 Class 的命名规范类似. 在满足 Classd 命名规则的基础之上, 保证开头第一个字母为 "I", 便于与普通的 Class 区别开. 其实现类名称取接口名的第二个字母到最后, 且满足类名的命名规范;
如: IMenuEngine
4, 枚举 ( Enum ) 的命名
基本与 Class 的命名规范类似. 在满足 Classd 命名规则的基础之上, 保证开头第一个字母为 "E" , 便于与普通的 Class 区别开.
如: EUserRole
5, 异常 ( Exception ) 的命名
异常 ( Exception ) 通常采用字母 e 表示异常, 对于自定义的异常类, 其后缀必须为 Exception
如: BusinessException
6, 方法 ( Method ) 的命名
方法名是一个动词, 采用大小写混合的方式, 第一个单词的首字母小写, 其后单词的首字母大写. 方法名尽可能的描述出该方法的动作行为. 返回类型为 Boolean 值的方法一般由 "is" 或 "has" 来开头
如: getCurrentUser() , addUser() , hasAuthority()
7, 参数 ( Param ) 的命名
第一个单词的首字母小写, 其后单词的首字母大写. 参数量名不允许以下划线或美元符号开头, 虽然这在语法上是允许的. 参数名应简短且富于描述.
如: public UserContext getLoginUser(String loginName);
8, 常量字段 ( Constants ) 的命名
静态常量字段 ( static final ) 全部采用大写字母, 单词之间用下划线分隔;
如: public static final Long FEEDBACK;
public static Long USER_STATUS;
三, 注释规范
一个很好的可遵循的有关注释的经验法则是:
问问你自己, 你如果从未见过这段代码, 要在合理的时间内有效地明白这段代码, 你需要一些什么信息???
1, 一般概念
1, 注释应该增加代码的清晰度
2, 保持注释的简洁
3, 在写代码之前或同时写注释
4, 注释出为什么做了一些事, 而不仅仅是做了什么
2, 注释哪些部分
1,Java 文件: 必须写明版权信息以及该文件的创建时间和作者;
2, 类: 类的目的, 即类所完成的功能, 以及该类创建的时间和作者名称; 多人一次编辑或修改同一个类时, 应在作者名称处出现多人的名称;
3, 接口: 在满足类注释的基础之上, 接口注释应该包含设置接口的目的, 它应如何被使用以及如何不被使用. 在接口注释清楚的前提下对应的实现类可以不加注释;
4, 方法注释: 对于设置 (Set 方法 ) 与获取 (Get 方法 ) 成员的方法, 在成员变量已有说明的情况下, 可以不加注释; 普通成员方法要求说明完成什么功能, 参数含义是什么且返回值什么; 另外方法的创建时间必须注释清楚, 为将来的维护和阅读提供宝贵线索;
5, 方法内部注释: 控制结构, 代码做了些什么以及为什么这样做, 处理顺序等, 特别是复杂的逻辑处理部分, 要尽可能的给出详细的注释;
6, 参数: 参数含义, 及其它任何约束或前提条件;
7, 属性: 字段描述;
8, 局部 ( 中间 ) 变量: 无特别意义的情况下不加注释;
3, 注释格式
遵循工程规定的统一注释格式, 一般情况下会以 codetemplates.xml 格式的文件导入 IDE(Eclipse)或者用 Eclipse 默认的;
四, 代码格式规范
遵循工程规定的统一代码格式, 一般情况下直接使用 IDE(Eclipse) 自带的默认代码格式对代码进行格式化;
1, 单行(single-line)-- 短注释://......
单独行注释: 在代码中单起一行注释, 注释前最好有一行空行, 并与其后的代码具有一样的缩进层级. 如果单行无法完成, 则应采用块注释.
注释格式:/* 注释内容 */
行头注释: 在代码行的开头进行注释. 主要为了使该行代码失去意义.
注释格式:// 注释内容
行尾注释: 尾端 (trailing)-- 极短的注释, 在代码行的行尾进行注释. 一般与代码行后空 8(至少 4) 个格, 所有注释必须对齐.
注释格式: 代码 + 8(至少 4)个空格 + // 注释内容
2, 块(block)-- 块注释:/*......*/
注释若干行, 通常用于提供文件, 方法, 数据结构等的意义与用途的说明, 或者算法的描述. 一般位于一个文件或者一个方法的前面, 起到引导的作用, 也可以根据需要放在合适的位置. 这种域注释不会出现在 HTML 报告中. 注释格式通常写成:
/*
* 注释内容
*/
3, 文档注释:/**......*/
注释若干行, 并写入 javadoc 文档. 每个文档注释都会被置于注释定界符 /**......*/ 之中, 注释文档将用来生成 HTML 格式的代码报告, 所以注释文档必须书写在类, 域, 构造函数, 方法, 以及字段 (field) 定义之前. 注释文档由两部分组成 -- 描述, 块标记. 注释文档的格式如下:
- /**
- * The doGet method of the servlet.
- * This method is called when a form has its tag value method
- * equals to get.
- * @param request
- * the request send by the client to the server
- * @param response
- * the response send by the server to the client
- * @throws ServletException
- * if an error occurred
- * @throws IOException
- * if an error occurred
- */
- public void doGet(HttpServletRequest request, HttpServletResponse response)
- throws ServletException, IOException {
- doPost(request, response);
- }
前两行为描述, 描述完毕后, 由 @符号起头为块标记注释. 更多有关文档注
释和 javadoc 的详细资料, 参见 javadoc 的主页: http://java.sun.com/javadoc/index.html
4,javadoc 注释标签语法
@author 对类的说明标明开发该类模块的作者
@version 对类的说明标明该类模块的版本
- //Rewriter
- //Rewrite Date:<修改日期: 格式 YYYY-MM-DD>Start1:
- /* 原代码内容 */
- //End1:
- //Added by
- //Add date:<添加日期, 格式: YYYY-MM-DD> Start2:
- //End2:
- //Log ID:<Log 编号, 从 1 开始一次增加>
- //Depiction:<对此修改的描述>
- //Writer: 修改者中文名
- //Rewrite Date:<模块修改日期, 格式: YYYY-MM-DD>
来源: http://www.bubuko.com/infodetail-2811254.html