命名与注释总结

一、命名

整洁的代码如同优雅的散文

软件中的命名随处可见。变量、函数、类、包以及模块的命名；jar文件、war文件以及ear文件的命名等。

1.1 命名原则

1.1.1 有意义的名称

变量、函数或类的命名应该能够表明了代码的大致意思。它应该告诉你，为什么存在，做了什么事以及如何使用。能够从名称中了解大概的含义，从下述代码可以看出，有意义的命名将会使得代码的可读性大幅提升。

// 糟糕的命名
int a;
int b;
int c;

// 有意义的命名
int hours;
int days;
int months;

1.1.2 避免误导

程序必须避免留下产生误导的地方，即一词多义。主要有以下几种情况：

• 变量名与关键字相同，导致含义出现不一致。例如：使用aix, sco等，以及为了表示容器，使用***List，实际上容器在不同的语言中有很多种表达形式；
• 使用外形相似度较高的命名。例如UserController VS UserInfoController，使用小写字母l和大写字母O作为变量名。

1.1.3 做有意义的区分

要区分名称，就要以阅读该代码的人能够轻易鉴别不同之处的方式来区分。以下是几种无效区分的例子：

example1:
反例：public static void copy(String s1, String s2){...}
正解：public static void copy(String source, String dest){...}

example2:
Product、ProductInfo以及ProductData,三者之间的含义没有什么区别，尽量不要其中的两者同时使用

1.1.4 命名要可读和可搜索

命名要尽量使用简单明了，避免生僻的英语词汇。例如：plateaux以及eyrie，基本上每次理解都需要费一番功夫，也不利于团队之间的交流。
可搜索指的是使用IDEA等软件的搜索功能时，输入查询词汇，返回的结果越少越好。主要针对的是单字母名称和数字常量，这些词汇可能在代码中最常用，每段代码基本上都有使用。例如：

public static final DEFAULT_START_PAGE = 0;
public static final LOG_EXPLESSION_NAME  = 'e';

类似于取一个有意义的命名规则，这样便于搜索。一般来说，单字母名称仅用于短方法中的本地变量，名称长短和其作用域大小相对应。

1.1.5 使用上下文语境简化命名

一个类属性名称、方法名称以及参数名称，能够通过上下文语境来推断其含义。例如：

class User {
	// 反例：
	private String username;
	private String userPassword;
	
	// 正解：
	private String name;
	private String password;
}
username以及userPassword中的前缀user是否有必要添加，个人认为没有必要。通过类名这个上下文就可以推断出是用户信息。

1.1.6 别使用双关语

整个项目中保持相同命名的术语，含义要一致。比如：insert插入数据，那么使用add，就属于双关语了，会给人一种两者是有区别的错觉，实际上并没有区别。

剩余的其他几条原则，可以参考书籍<代码整洁之道>。

1.2 实际场景

1.2.1 类名和方法名命名问题

• 类名和对象名一般使用名词或名词短语，不应当是动词；方法名表示做什么，应当是动词或动词短语。
• 命名多长比较合适

1. 对于大家都熟知的词汇，推荐使用缩写. String -> str, Object -> obj, number -> num等
2. 对于作用域比较小的【方法内的局部变量】，推荐短命名；
3. 对于作用域比较大的，推荐长命名。

• 接口和抽象类的命名

多种方式：
方式1: 接口使用前缀I; 例如：IUserService,实现类为UserService
方式2: 接口不加前缀; 例如：UserService,实现类为UserServiceImpl
方式3: 接口使用前缀I; 例如：IUserService,实现类为UserServiceImpl
方式4: <代码整洁之道>的作者推荐不添加修饰的接口, 无需告诉用户这是一个接口,只需要知道我提供给你什么服务就可以。例如: BeanFactory为什么不使用IBeanFactory,大家都可以思考一下。

• 重载构造器优雅使用方式

《代码整洁之道》作者推荐使用静态工场来描述重载的构造器:
People people = People.createRealPeople("xiaoming")

二、注释

注释是对代码的补充性说明，注释有一下的作用：

1. 命名主要体现的是"做什么", 注释可以更加详细的解释"为什么"以及"怎么做"的问题，即注释承载的信息会比代码更多;
2. 注释起到总结性或文档的作用
3. 一些总结性注释会使得代码结构更加清晰

**注释的缺点：**注释存在的时间越久，离其要解释的代码意图越远，随着代码的变动，腐化越来越严重。因此，《代码整洁之道》书中认为：

注释就是弥补我们用代码表达意图时遭遇的失败，即存在虚假成分。真实只在一处地方：代码，只有代码能够忠实的告诉你它做的事

因此，最佳实践为：优先使用考虑给代码优雅命名，用代码来表述含义；其次，注释采用总结性的方式来辅助代码阐述真正的意图，注释越少越好。
相关例子为：

// example1:
// check password
if(user.getPassword() != null && user.getPassword() >= 0
&& user.getPasswork() < 50){...}

消除注释的方式:
if(isValidatePassword(user)){...}
private boolean isValidatePassword(user) {
	return user.getPassword() != null && user.getPassword() >= 0
&& user.getPasswork() < 50);}

// example2:
private void startSending() {
	try {
		doSending();
	} 
	catch(SocketException e) {
		// someone stopped the request
	} catch(Exception e) {
		try{
			doSomething();
		} catch (Exception e) {
			// blabla.废话注释
		}
	}
}
正解:
private void startSending() {
	try {
		doSending();
	} 
	catch(SocketException e) {
		// someone stopped the request
	} catch(Exception e) {
		processException();
	}
}

private void processException() {
	try{
		doSomething();
		} catch (Exception e) {
		}
}

三、总结

命名和注释是一个非常主观性的事情, 但是优雅简洁的命名以及注释可以从很大程度上提高代码的可读性。如何更好的平衡命名和注释，需要从工作中不断的实践，感受以及思考。上述总结来源于《代码整洁之道》等资料，并非强制规定，只是提供一个比较好的参考方法，详情可以阅读《代码整洁之道》。