Clean Code 笔记之第四章如何应用注释

继上一篇笔记之后，今天我们讨论一下代码中是存在注释是否是一件好的事情。

在我们开发的过程中讲究“名副其实，见名识意”，这也往往是很多公司的要求，但是有了这些要求是不是我们的代码中如果存在注释是不是意味着我们的函数，变量，以及类的命名就不符合了“名副其实，见名识意”。

我们先区分一下注释的类别，注释一般分为以下几种：

1，单行注释
2，多行注释
3，文档注释
4， #region 折叠注释，可以将代码折叠

注释的类别

1， 单行注释：

在以 “//” 开头，用以说明一行代码的作用放置位置看习惯或者公司要求合理就行。常用于函数内部，在很多的开源代码中文件的头部我同样见到很多人使用单行注释进行说明，灵活就好。
体现形式如下：

 public List<string> getVipUserNameByUserType()
          {
            // Vip user name list
            var vipUserNames = new List<string>();

            foreach (var user in Users)
            {

                if (user.Type = "VIP")

                    vipUserNames.Add(user.Name);
            }
            return vipUserNames;

          }

2， 多行注释：

以“/*”开头 “*/” 结尾常用于描述说明一段代码以及类注释或者说代码块常用于文件的顶部。说明作者信息，时间如果是开源的这包含开源的更多说明。
通常使用如下:

/*
    * 作者：〈版权〉
    * 描述：〈描述〉
    * 创建时间：YYYY-MM-DD
    * 作用：
*/

3， 文档注释：

也就是常用的XML 注释：它的说明性更加的强烈，多用于类以及函数上，当然属性上同样可以使用：
如下所示：

        /// <summary>
        /// MyClass
        /// </summary>
        public class MyClass
        {
            /// <summary>
            /// MyProperty
            /// </summary>
            public int MyProperty { get; set; }
            /// <summary>
            /// MyMethod
            /// </summary>
            public void MyMethod(){  }
        }

以下是官方建议的文档标记点击标签会制动跳转

4， #region ：折叠注释，常用于描述多个函数的基本作用

书中最喜欢的话

好的注释不能美化糟糕的代码，真正好的注释是你想尽办法不去谢的注释。怀注释都是糟糕代码的支撑或借口，或者是对错误决策的修正。

下面看一个例子

       //Check to see if the employee is eligible for full benefits
（）If((employee.flags & HOURLY_FLAG)&& (employee.age>))

（）If(employee.isEligibleForFullBenefits()))

  这两个你更喜欢哪个

好的注释的特征：

1：表示法律信息（这样的注释一般出现在文档顶部说明作用以及协议）

// Copyright (c) .NET Foundation. All rights reserved
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.

2：提供信息的注释（指无法通过命名提供信息如要注释辅助的）

public void ConfigureServices(IServiceCollection services)
{

// These two middleware are registered via an IStartupFilter in UseIISIntegration but you can configure them here.

services.Configure<IISOptions>(options =>
{});

}

3：对意图的解释

4：警示：告知其他人会出现某种后果的注释

5： TODO注释：主要描述应该做的目前还没有做的事情。

6：放大：提示不合理之物的重要性。

应避免的注释

应该避免以下几点：

1：误导性注释

2：日志式注释

3：废话注释

4：标记位置的注释

5：括号后的注释

6：归属与签名

7：注释掉的代码

8： Html 注释

以上没有一一举例的原因是我的PPT是一份演示的PPT，里面很多公司的代码不便贴出，抱歉。

不足之处还请指出