这里说的开发规范分成目录规范,项目和包名的命名规范,类,方法,变量和常量的命名规范这几种。
目录规范
目录规范——在开发中整体文件夹组织结构。
- Requirement——需求文档文件夹
- Design——设计文档文件夹
- Test——集成测试,系统测试,测试报告,测试清单文件夹
- Deployment——发布部署的文件夹
- Study——预研,学习资料的文件夹
- Src——源码文件夹
- Help——帮助文档文件夹
这么组织文件有什么好处,就是一个项目做完以后,所有的资料就也完成了,结构一目了然。
常见的命名方法
- 匈牙利命名法:该命名法是在每个变量名的前面加上若干表示数据类型的字符。基本原则是:变量名=属性+类型+对象描述。如i表示int,所有i开头的变量命都表示int类型。s表示String,所有变量命以s开头的都表示String类型变量。
- 骆驼命名法:正如它的名称所表示的那样,是指混合使用大小写字母来构成变量和函数的名字。驼峰命名法跟帕斯卡命名法相似,只是首字母为小写,如userName。因为看上去像驼峰,因此而得名。
- 帕斯卡命名法: 即pascal命名法。做法是首字母大写,如UserName,常用在类的变量命名中。
- 下划线命名法:下划线法是随着C语言的出现流行起来的,在UNIX/LIUNX这样的环境,以及GNU代码中使用非常普遍。
项目和包名命名规范
对于项目和包名命名规范是
- 包名一律小写, 少用缩写和长名;
- 采用以下规则:
- [基本包].[项目名].[模块名]
- 包名一般不要超过三级,级别多了费脑子
- 不得将类直接定义在基本包下,所有项目中的类、接口等都应当定义在各自的项目和模块包中;
例如:
package com.lcw.test.util;
这样子的规范,能够提高项目组织性,从而便于更好的协同开发。
类和接口的命名
- 类或接口名是个一名词,采用大小写混合的方式,每个单词的首字母大写。
- 尽量使你的类名简洁而富于描述。
- 使用完整单词,避免用缩写词(除非该缩写词被更广泛使用,像URL,HTML)。
例如:
class Raster;
class ImageSprite;
interface RasterDelegate;
interface Storing;
命名采用单词组合取名,单词首字母为大写,单词之间可采用“_”下划线进行区分,也可不采用。
根据定义类型首字母加以区分:
- Interface:命名首字母加大写的“I”;
- Abstract class:命名首字母加大写“A”;
- Class:无需加
根据功能类型结尾加上功能描述字符串:
- 页面类:“Page”,例如“LoginPage”
- 处理类:“Handle”,例如“LogicHandle”
- 工厂实现类:“Impl”,例如“FactoryImpl”
- 动作事件定义类:“Action”,例如“LoginAction”
- 网络事件定义类:“Net”,例如“LoginNet”
- 数据定义类:“Data”,例如“LoginData”
- 消息处理类:“Msg”,例如“LoginRequestMsg”
- 资源管理类:“Manager”,例如“ImageManager”
- 缓存类:“Cache”,例如“UserCache”
- 参数传递类:“Param”,例如“LoginParam”
- 功能提供类:“Util”,例如“MathUtil”
- 数据输入输出类:“Steam”,例如“CacheOutStream”
注意事项
- 类命名不能使用中文字符,不能在命名字符串中出现“0-9”的数值描述和除下划线以外的其他字符描述,命名的字母组合尽量能够在本身的文字意义上初步了解类的大体功能。
- 好的类的命名是,不见注释见名知意。
- 采用大小写混合的方式,第一个单词的首字母小写,其后单词的首字母大写
变量命名方法
- 变量名不应以下划线或美元符号开头;
- 尽量避免单个字符的变量名,除非是一次性的临时变量。临时变量通常被取名为i,j,k,m和n,它们一般用于整型;c,d,e,它们一般用于字符型;
- 不建议采用匈牙利命名法则,对不易清楚识别出该变量类型的变量应使用类型名或类型名缩写作其后缀
- 组件或部件变量使用其类型名或类型名缩写作其后缀
- 集合类型变量,例如数组和矢量,应采用复数命名或使用表示该集合的名词做后缀
例如
Thread animationThread;
String responseStr; Command backCommand;
Image barImage;
TextField passwordField;
Player dogSoundPlayer; Image[] images;
Vector requestQueue;
常量命名
- 全部采用大写,单词间用下划线隔开
- static final int MIN_WIDTH = 4;
- static final int MAX_WIDTH = 999;
- static final int GET_THE_CPU = 1;
方法命名
- 方法名是一个动词,采用大小写混合的方式,第一个单词的首字母小写,其后单词的首字母大写;
- 取值类可使用get前缀,设值类可使用set前缀,判断类可使用is(has)前缀。
- 对于方法中一定要加上适当的非空判断,与try catch 语句等等程序健壮性的判断
getName();
setSarry();
isLogon();
注释
- 注释,是程序维护的灵魂。
- 原则——对已经不推荐使用的类和方法需要注明@Deprecated,并说明替代的类或者方法;
- 对于针对集合、开关的方法,要在方法注释中表明是否多线程安全。
文件注释
- 所有的源文件都应该在开头有一个注释,其中列出文件的版权声明、文件名、功能描述以及创建、修改记录
/*
* Copyright (C) 2009-2014 liucw Inc.All Rights Reserved.
* FileName:HelloWorld.java
* @Description:简要描述本文件的内容
* History:
* 版本号 作者 日期 简要介绍相关操作
* 1.0 liucw 2014-03-21 Create
* 1.1 liucw 2014-03-23 Add Hello World
*/
类或接口注释
- 采用JavaDoc文档注释,在类、接口定义之前应当对其进行注释,包括类、接口的描述、最新修改者、版本号、参考链接等
/**
* 描述
* @author liucw(最新修改者)
* @version 1.0 (最新版本号)
* @see 参考的JavaDoc
*/
class Window extends BaseWindow
{
...
}
JavaDoc文档注释:
- 描述Java的类、接口、构造方法、方法、以及字段。
- 每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类、接口或成员。
- 该注释应位于声明之前。
- 文档注释的第一行(/**)不需缩进,随后的文档注释每行都缩进1格(使星号纵向对齐)。
方法注释
- 采用JavaDoc文档注释,在方法定义之前当对其进行注释,包括方法的描述、输入、输出及返回值说明、抛出异常说明、参考链接等
/**
* @author liucw
* @Description: ${todo}
* @date ${date} ${time}
* @param 参数说明:每个参数一行,注明其取值范围等
* @return 返回值:注释出失败、错误、异常时的返回情况
* @exception 异常:注释出什么条件下会引发什么样的异常
* @see 参考的JavaDoc
*/ public char charAt(int index)
{
...
}
其它注释(非JavaDoc文档注释)
- 单行代码注释一律使用注释界定符"//"
// explain what this means
if(bar > 1)
{
……
}
int isShow = 0;// 是否显示
- 多行注释使用注释界定符"/*...*/"
/*
* Here is a block comment with
* multiple lines for text comments.
*/
这些命名规范和注释,看似是微不足道一小步,却是我们通往专业的一大步