Skip to content

Latest commit

 

History

History
192 lines (150 loc) · 5.43 KB

注释.md

File metadata and controls

192 lines (150 loc) · 5.43 KB
Raw

简洁明了的注释有利于代码的阅读和理解，但不必要的注释则会增加代码的维护难度。

五种应该避免的注释

下面列举了几种不好的注释习惯，并且给出了改进建议：

1. 注释重复描述代码已清晰表述的意思

namespace CleanCSharp.Comments.Dirty
{
    // This defines a class called BasicCalculator 
    public class Calculator
    {
        // Define default constructor 
        public Calculator() { }

        // Define a method to add two numbers 
        public int AddTwoNumbers(int a, int b)
        {
            // declare an int to hold result int result;
            // set result to sum of a and b 
            result = a + b;

            // return the result to the caller 
            return result;
        }
    }
}

上段代码中，明显注释过多，且用于描述代码已经表述清楚的内容。这样做，不仅对阅读代码没有帮助，还会显得代码臃肿。

注意以下注释：

 // This defines a class called BasicCalculator 
public class Calculator

这句注释没有什么意义，并且注释中还把类名写错。注释应当与代码同步更新，代码中的无用注释会在这方面耗费开发人员过多的精力。

对上述代码进行精简，如下：

namespace CleanCSharp.Comments.Dirty
{
    public class Calculator
    {
        public int AddTwoNumbers(int a, int b)
        {
            result = a + b;

            return result;
        }
    }
}

去除了无用注释及默认无参构造函数后，代码结构更加清晰且更具可读性。

2. 版本控制中的注释

namespace CleanCSharp.Comments.Dirty
{
    /* 10 Oct 2010 Sarah Smith - Created initial version 
    * Edited 20 Oct 2010 Amrit P - change calculation method 
    * Edited 20 Nov 2010 Jane Q - fix defect 4286 
    */
    public class MyClass { }
}

上述代码中的注释，主要描述了何时，以及为什么对文件做了修改。

如果代码已被添加到版本控制系统中，那么这些注释就没有必要存在。如果还没有使用版本控制系统，那么，建议你使用版本控制系统对源代码进行管理。

3. 使用多余的注释而非自描述的命名

namespace CleanCSharp.Comments.Dirty
{
    public class SimpleCalculator
    {
        // Add two numbers together 
        public int Calculate(int a, int b)
        {
            return a + b;
        }
    }
}

这里的注释可以用良好的方法命名来替代：

namespace CleanCSharp.Comments.Dirty
{
    public class SimpleCalculator
    {
        public int AddNumbers(int a, int b)
        {
            return a + b;
        }
    }
}

良好的命名不需要额外的注释来解释，尽可能使用良好的命名来替代注释，而不是用注释解释难以理解的命名。

4. 注释掉的代码

有时，我们会在代码库中看到已被注释掉的代码，如下所示：

namespace CleanCSharp.Comments.Dirty
{
    public class AnotherSimpleCalculator
    {
        public int AddNumbers(int a, int b)
        {
            // a = a + 42;
            return a + b;
        }
    }
}

上述代码中的注释// a = a + 42;会让人疑惑，我们即不清楚这段代码的作用，也不明白它为什么会被注释掉。像这种让读者疑惑的注释降低了代码的可读性。

对于无用（或感觉将来可能有用）或开发中临时添加的代码，不应被直接注释掉，而应尽可能删除，如果需要，我们可以在版本控制系统中查看。

如需保留被注释掉的代码，也应说明注释调的原因及在何种情况下可以恢复。

5. 无意义的XML注释

namespace CleanCSharp.Comments.Dirty
{
    /// <summary> 
    /// 
    /// </summary> 
    public class BasicCalculator
    {
        /// <summary> 
        /// Adds two numbers 
        /// </summary> 
        /// <param name="a"></param> 
        /// <param name="b"></param> 
        /// <returns></returns> 
        public int AddNumbers(int a, int b)
        {
            return a + b;
        }
    }
}

虽然IDE会因为我们没有给某个方法或类添加XML注释而生成警告，但我们不应因此而增加无意义的XML注释。

上述代码有近乎一半的篇幅被无意义的XML文档所占据，这会对代码的阅读造成视觉干扰，降低代码阅读效率。下面是去掉XML注释后的代码，简介而又有着良好的可读性。

namespace CleanCSharp.Comments.Dirty
{
    public class BasicCalculator
    {
        public int AddNumbers(int a, int b)
        {
            return a + b;
        }
    }
}

通常暴露给第三方调用的API，需要添加较为完备的XML文档注释，以辅助调用方理解API，此时对于XML文档的冗余问题则另当别论。

小结

综上，总结写注释的几点小建议：

  1. 在编码时尽可能使用良好的命名以达到代码的自描述，这样可以少写注释且可避免注释的词不达意；
  2. 若非必要，勿添加注释，注释的维护工作也是相当耗费精力的；
  3. 程序中尽可能不要遗留被注释掉的代码，以免给后来者造成困惑；

一句话：注释是为提升代码可读性和可维护性而存在，若你的注释达不到这个目的，则应考虑是否还有保留注释的必要性。

推荐阅读

Redis是如何写代码注释的？