这是我参与更文挑战的第9天，活动详情查看：更文挑战

编写可读代码 – 注释

首先我们要清楚我们为什么要写注释，当然是为了记录当下的思想、日后能够更好的去理解，节省维护成本对吧！

当我们重新读已写过的代码时，阅读注释代码比阅读真实代码耗费的时间可能要更多些，并且注释也是占有空间的，所以需要去考虑哪些注释代码是值得记录下来的

不要为了注释而注释

// 1、很明显代码再做的事 我们就不要去注释啦
// bad - 数组根据line分割后取到的符号组成字符串 - 
var name = ['xi', 'yyds'].join(line.split('*')[1])

// 2、不要为没有命名好的函数名添加注释，而是应该把函数名做好，去掉注释
// bad - 把number 转成 字符串格式 
function toStr(number) {}
// good
function numToStr(number) {}
复制代码

记录你的思想

通过上面知道了该摒弃什么、记录什么了，在代码演进的过程中肯定是有瑕疵的，我们应当把要注意的事项，以及将来可能要做的事情写下里，采用如下流行的规则

通过 这种记录当下的思想，给读者阅读带来启发、甚至能给给他们提供如何改进的方向

// 避免使用像tmp、retval、foo、bar这样的名字
function dealData(url) {
	let retval = null
	...
	return retval
}
// 上述例子中 retval 只能表明‘我是一个返回值’得含义，并不能给读者带来更多的信息

// 当然有些时候泛泛得名词也能有很好的效果, 例如下例这种经典场景
 if (right < left) {
 	 let tmp = right
 	 right = left
 	 left = tmp
 }
复制代码

站在读者的角度

• 预料一些代码会让人产生误会，在这些代码上加注释，注明为什么这么做
• 在文件/类的级别上使用“全局观“的注释来解释所有的部分是如何一起工作的
• 用注释来总结代码块，使读者不致迷失在细节中

写出言简意赅的注释

• 让注释保持紧凑
• 避免使用不正确的代词
• 润色粗糙的句子
• 精确的描述函数的行为
• 用输入/输出例子来说明特别的情况
• 声明代码的意图
• ”具名函数参数“的参数
• 采用信息量高的词