Clean-Code: 注释

别给糟糕的代码加注释-----------------重新写吧

 

这是书中的关于注释一章的第一句话，怎么说呢，这句话个人感觉很对，但是实际上却很少这么做，

有几个原因：

• 糟糕的代码不是自己写的，别人写的代码，还是让别人自己去维护吧，出了问题也是别人的。
• 糟糕的代码目前可以正常工作，软件开发中有一条古老哲言：如果它能工作就不要动它，很多程序员都遵守这条准则。
• 既然代码不能被修改，那么就只能加注释了。

上面的几个原因纯粹是自己的想法，希望你不要和我一样。

注释的好处基本上大家都知道，主要是为了方便其他人更好的查看和理解代码，下面的一些主要是乱用注释而导致的坏处：

 

可怕的注释，废话注释：

// the name

private string name;

// the version

private string version;

// the licenceName

private string licenceName;

// the version

private string info;

上面的代码注释的确多余了，并且还有剪切-粘贴错误，我想这可能是因为作者是外国人，所以对外国人来说英语是母语。但是中国的程序员大部分都用中文注释。所以上面的代码可能是这样：

// 姓名

 private string name;

 // 版本号

 private string version;

 // 许可名称

 private string licenceName;

 // 信息

 private string info;

 

虽然注释一样有些多余，不过对于英文不好的读者来说的确方便了不少。

 

下面的示例是我从某位大师的系统中抽取出来的

 

/// <summary>

/// IBaseManager

/// 通用接口部分

///

/// 总觉得自己写的程序不上档次，这些新技术也玩玩，也许做出来的东西更专业了。

/// 修改纪录

///

///     2007.11.01 版本：1.9 jjjco 改进 BUOperatorInfo 去掉这个变量，可以提高性能，提高速度，基类的又一次飞跃。

///     2007.05.23 版本：1.8 jjjco 修改完善了 对象事件触发器，完善了GetDT, ref 方法部分。

///     2007.05.20 版本：1.7 jjjco 修改完善了 对象事件触发器，完善了GetDT方法部分。

///     2007.05.19 版本：1.6 jjjco 修改完善了 Delete，Exists方法部分，累了休息一下下，争取周六周日两天内完成。

///     2007.05.18 版本：1.5 jjjco 规范了一些接口的标准方法，进行了补充。

///     2007.05.17 版本：1.4 jjjco 重新调整主键的规范化，整体上又上升了一个层次了。

///     2006.02.05 版本：1.3 jjjco 重新调整主键的规范化。

///     2005.08.19 版本：1.2 jjjco 参数进行改进

///     2004.07.23 版本：1.1 jjjco 增加了接口ClearProperty、GetFromDS 的定义。

///     2004.07.21 版本：1.0 jjjco 提炼了最基础的方法部分、觉得这些是很有必要的方法。

///

/// 版本：1.8

///

/// <author>

///     <name>jjjco</name>

///     <date>2007.05.23</date>

/// </author>

/// </summary>

public interface IBaseManager

{

    xxxxxx

}

 

这段注释有几个问题：

1. 喃喃自语，
2. 修改记录在有源代码管理的情况下，完全多余，不过鉴于最早的版本是 2004.07.21, 这一点，修改记录问题也不大。
3. 注释中版本的不一致，最新的版本是 2007.11.01 的版本 1.9 . 但是下面显示的版本是 1.8. 版本不一致的原因是作者忘记了，包括下面的 <date> 2007.05.23 </date>

 

#region 注释

msdn  解释：

#region 使您可以在使用 Visual Studio 代码编辑器的 大纲显示功能时指定可展开或折叠的代码块。 在较长的代码文件中，能够折叠或隐藏一个或多个区域会十分便利，这样，您可将精力集中于当前处理的文件部分。

 

#region MyClass definition

public class MyClass

{

    static void Main()

    {

    }

}

#endregion

 

效果如下：

记得以前我刚接触#region的时候，习惯性的写上了这样的代码：

 

对于经常使用#region的同学肯定知道上面的代码的问题。#region 后面是不需要加 “//” 的。

 

大师不愧是大师，另一个经典的注释是让你忘记不了他是如何使用#region的。

当我看到DbLogic的时候，我彻底崩溃了。

不过在批评别人的同时，我还是要说下大师的优点：

 

1. 代码结构清晰
2. 命名相对来说还算规范
3. 注释非常详细，虽然像上面的注释不在少数，但是不可否认的是注释非常详细，比如：