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;

          }

View Code

2， 多行注释：

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

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

View Code

3， 文档注释：

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

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

View Code

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

 

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

书中最喜欢的话

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

下面看一个例子

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

（2）If(employee.isEligibleForFullBenefits()))

  这两个你更喜欢哪一个

View Code

好的注释的特征：

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.

View Code

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 =>
{});

}

View Code

3：对意图的解释

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

5： TODO注释： 主要描述应该作的目前尚未作的事情。

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

应避免的注释

应该避免如下几点：

1： 误导性注释

2： 日志式注释

3： 废话注释

4： 标记位置的注释

5： 括号后的注释

6： 归属与签名

7： 注释掉的代码

8： Html 注释

以上没有一一举例的缘由是个人PPT是一份演示的PPT，里面不少公司的代码不便贴出，抱歉。

不足之处还请指出