《编写可读代码的艺术》---写出言简意赅的注释

什么是言简意赅？

年轻的时候，我们很多时候因为紧张，导致语无伦次，话说了很多，但是别人不知道你在瞎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

//统计文件内容里有多少个换行符 (
)

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);

有以下几点，可以让输入/输出的例子变得直观：

1. array中包含compareNumber，用来解释分区的边界情况
2. array中包含重复的数字，用于表示，这是一个可以接受的情况
3. array默认的顺序是杂乱的，用来更好的对比函数的运行结果
4. 返回的值是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种设计模式，当你花费了很大篇幅来描述一个代码块的时候，一个“这里采用了 抽象工厂设计模式”可能会让人更加直观。