《代码整洁之道》---4. 重要的注释---学习记录

---

注释

注释是，是优雅代码的无用，是平常代码的补充，是糟糕代码的说明。它并不是一种友好的方式。

---

1. 注释并不美化代码

一般越糟糕的代码使用到注释的可能性越大，如果真的是为糟糕的代码写注释，那不如将代码掀翻重新写。

---

2. 用代码来阐述

我们可以尽量用可视化的命名来让阅读代码的人理解我们的意思，而不是使用注释。

---

3. 需要的注释

3.1 法律信息

有时公司会在项目前面加上与法律有关的注释。例如版权和著作权。

---

3.2 提供信息的注释

举个例子：

//通过id获取名字
public string getName(string id){
	...
}

这里是说注释还是能提供一定信息的。

当然我们可以通过换个名字也可以得到差不多的效果。

public string getNameById(string id){
	...
}

---

3.3 对意图的解释

这里是对某一奇怪操作的代码行进行说明，比如突然生成一个变量，或者是新建一个循环。

---

3.4 阐释

阐释就是把某些难懂的乱七八糟的代码在其后添加上具体语句描述这些代码是什么意思。

---

3.5 警示

可以用来警示后来人做什么事会有什么后果。比如说：

//运行这个程序你将发消息给leader说：一起打羽毛球
public void sendMsg(string sendMsg){
	...
}

3.6 TODO注释

这个注释用来描述一个将来会做的状态。通过这个来定义好规范。

//TODO:作用，运行这个程序你将发消息给leader说：一起打羽毛球
public void sendMsg(string sendMsg){
	//TODO:待实现
}

---

3.7 放大

这里的放大是指让一些代码里不合理的地方，可能只有一行代码，但是可以通过添加注释，让这个不合理的地方更容易被发现。

---

3.8 良好描述的公共API

这里是指在做API的时候应该有一段良好的描述（如果有需要的话）。例如JAVA中的Javadoc。

---

4. 坏注释

---

4.1 写给自己看的注释

一些注释，写的人会从自己的角度出发，默认读者知道自己在说什么知道自己知道的事情，轻易的在注释里面写下了和其他模块有关的注释。

这样就要让读者在看这个代码的时候，还要跳到别的模块阅读代码。

---

4.2 多余的注释

当注释没有更多于命名带来的意义或者本身就没有意义的时候，这样的注释就很多余。

---

4.3 误导性的注释

注释是为了让阅读代码的时候更加清楚的知道代码的意思，而不是让人产生代码和注释不能相互印证的模糊感。这样反而会加大阅读的难度。

---

4.4 循规式注释

每个函数都要拥有自己的注释，这样导致代码阅读起来就会很耗费时间。

---

4.5 日志式注释

每次修改都会添加日志注释，但是现在我们编译器已经可以控制具体的版本了，或者使用版本控制，而不是添加日志般的注释。

---

4.6 废话注释

没有意义的注释。耗费编写和阅读的时间。

---

4.7 可怕的废话

当注释没有含义，甚至是错误的注释就会给人带来很大的困扰。
举个例子：

/** The name*/
private String name;

/** The name*/
private String version;

像例子中的一样，这里的version的注释是the name，这给人的感觉就是写代码的人从上面复制了代码，但是就忘记改名了。

但是谁也说不准,对吧。

---

4.8 能用函数和变量就别用注释

当我们在看代码的时候看到一长串的代码，然后上面添加了一串注释，虽然注释有助于我们理解，但是我们也可以把这个长传的代码分解出来，这样就不需要写注释了。

举个例子：

	//通过id拿到name和password再获取user对象
	if(getUser(getUserNameById(String Id)),getPasswrodById(String Id))){
		...
	}

这一长串的代码有什么意义呢。不如把他分解出来。

	String name = getUserNameById(String Id));
	Strinng password = getPasswrodById(String Id);
	result = isUser(name, password)
	if(result){
		...
	}

这样就不会有看到长代码的烦恼。

---

4.9 位置标记

在程序中使用注释来标记一个位置，或者是函数，或者是变量。

举个例子：

//Action 	/
public void action(){
	...
}

这个Action /看不出价值。原意是把特定函数趸放在着各种标记栏下，但是我看不出来有什么价值。可能是我的问题把。。

---

4.10 括号后面的注释

在括号后面的注释，原意是想要看到这个括号的时候知道这个括号是属于哪个部分的。

但是随着编译器的升级，这个功能也有点无用。

举个例子：

	...
	try{
		...
	}//try
	catch(IOException e){
		...
	}//catch
	...

这种情况可能在长代码里面会出现，但是我们也应该想办法去避免长代码，而不是去加个注释去弥补代码过程导致的问题。

---

4.11 归属和署名

有种注释是写了作者是谁，可能原先是为了代码遇到问题，知道能和谁进行讨论。

但是代码控制系统已经能出色的完成这种事情了，不需要添加这些奇怪的注释。

举个例子：

/* Added by Rick*/

---

4.12 注释掉的代码

注释掉的代码，除非原先编码人主动去删，否则后来者看到也不知道这段东西的作用，也不敢轻易的删除。

所以最好的办法是我们不这么干。一旦决定这个程序可以了，就可以删除掉了。

---

4.13 HTML注释

当需要展示关于HTML的注释的时候，应该由工具自动添加，而不是用编码人直接手写。

---

4.14 注释信息越级

当函数提供的信息超过本函数级别的时候，就会出现注释信息提示越界的问题。

越界指的是注释的内容超过本函数的东西，甚至涉及到该函数组成的系统的内容。

结论：要写注释就确保它描述了离它最近的代码。

---

4.15 信息过多

不要在注释中提及无关本函数的信息，例如有幽默的话语，历史变更等无关信息。

---

4.16 不明显的联系

在注释写下的时候就注定它的功能是描述看不懂的代码。

所以要确保写下的注释是能够看懂的，而不是需要再写注释去解释这之前难懂的注释。

---

4.17 函数头

短函数不需要太多描述，选个好的函数名，比写函数头注释要好。

---

4.18 非公共代码中的Javadoc

可以理解成一种固有格式的注释说明。因为格式繁琐。如果不是公共使用的话，就会写的代码总长度很长。

---

注释一章就此结束，但是这章的学习，由例子可见的写的潦草，如果有需要想更深入学习的同学建议阅读《clean code》