《编写可读代码的艺术》---写出言简意赅的注释
什么是言简意赅？
年轻的时候，我们很多时候因为紧张，导致语无伦次，话说了很多，但是别人不知道你在瞎BB啥。
所以要经常写博客哟~可以锻炼我们对语言提炼的能力
言简意赅可以分为两个部分
- 言简：尽量凝炼语言，减少注释在屏幕上的空间占用。
- 意赅：如果你要写注释，就要明确你所要表达的意思。
以下是一些针对“言简意赅的注释原则”所提供的建议：
1 对号入座
一个函数，有函数名，参数，返回值，这些如果我们自己手工去一一指定的话，就会吃力不讨好。
善用IDE提供的快捷键(///)，可以帮助我们简化这个过程(visual studio2010为例)
/// <summary> /// 获得指定合同所属的补充合同的集合 /// </summary> /// <param name="CGUID">公司GUID</param> /// <param name="CRGUID">合同GUID</param> /// <returns>合同的集合</returns> public DataTable GetModelList(Guid CGUID, Guid CRGUID)
2 润色粗糙的句子
“言简”的句子，同样是“意赅”的保证
来个网页爬虫的例子：
坏：BAD
//根据我们是否已经抓取过这条数据，来决定是否给它更高的优先级
好：GOOD
//如果没有抓取过该数据，则优先级更高
3 避免使用第三人称（它、他、她）
如果一个句子中涉及的对象超过两个，使用第三人称会带来迷惑，这个时候，就使用具体对象名来替代第三人称。
来个缓存的例子：
坏：BAD
//把取出的数据插入到缓存中，但是先检查下它是否过大
我们根本不知道“它”指的是数据还是缓存？
好：GOOD
//把取出的数据插入到缓存中，但是先检查下数据是否过大
4 精确描述函数的行为
笼统的方法名称可能会模糊它特定的工作方式。
来个统计文件行数的例子
int CountLine(string fileName);
坏：BAD
//返回文件内的行数
看到这里读者可能就有疑惑了，这个函数是根据什么标准，来区分行的呢？
好：GOOD
//统计文件内容里有多少个换行符 (\n)
5 使用输入/输出的例子来说明情况
比如我们有个函数，是对是对数字数组进行分区,具体原理请看下面的注释
//对数组进行排序，使得小于compareNumber的元素靠前 //返回排序后的最大的数组下标i，当array[i]小于compareNumber的时候（如果元素都比compareNumber大，返回-1） int PartitionArray(int[] array, int compareNumber);
嗯，上面的注释很精确了，但是还欠直观，我们可以用下面的例子来让他变得一目了然
//对数组进行排序，使得小于compareNumber的元素靠前 //返回排序后的最大的数组下标i，当array[i]小于compareNumber的时候（如果元素都比compareNumber大，返回-1） //比如：PartitionArray({8,5,9,8,2},8) 数组的顺序被调整为{5,2,8,9,8}，返回1 int PartitionArray(int[] array, int compareNumber);
有以下几点，可以让输入/输出的例子变得直观：
- array中包含compareNumber，用来解释分区的边界情况
- array中包含重复的数字，用于表示，这是一个可以接受的情况
- array默认的顺序是杂乱的，用来更好的对比函数的运行结果
- 返回的值是1，此时我们要确保array中不包含1，否则可能会引起困惑
6 声明代码的意图
正如前几章提到的，很多时候注释是要告诉读者，当你写代码的时候，你是怎么想的；遗憾的是很多注释没有完成传递你创作代码的意图的任务，而只是潦草地在字面上描述代码的功能
不好：Bad
static void DisplayProducts(List<Product> products) { //对产品的数组按照价格从高到低进行排序，并输出他们的价格 products.Sort((firstProduct, secondProduct) => firstProduct.Price > secondProduct.Price ?1 : 0); products.ForEach(a => { Console.Write(a.Price); }); }
好：Good
static void DisplayProducts(List<Product> products) { //从高到低输出产品的价格 products.Sort((firstProduct, secondProduct) => firstProduct.Price > secondProduct.Price ?1 : 0); products.ForEach(a => { Console.Write(a.Price); }); }
7 采用信息含量高的词语
一旦你写了多年的程序以后，你会发现有些普遍的问题和解决方案会重复出现，通常会用专门的词语来描述这种模式/方式。使用这些词语会让你的注释更加紧凑
比如24种设计模式，当你花费了很大篇幅来描述一个代码块的时候，一个“这里采用了 抽象工厂设计模式”可能会让人更加直观。
