我为什么拒绝写注释

      其实没有人问过我为什么不写注释，我也没有向别人说过我不写注释的原因。但是最近一直有人在我耳边说，你们这些鸟人为什么都不写注释了。所以我觉得我有必要做一下解释了。

      第一、什么情况下需要注释。如果你面对的受众是一些初学者或者非专业的人员，那么确实需要写注释，这一点在教科书上体现的最多。又或者，你所工作的语言是结构化编程之类的没有很强的层次性（包或者命名空间）和封装（类），那么你需要写注释(C是最好的例子）。最后，如果你写的是算法，或者你的函数中有魔数之类的东西，你需要加注释，比如如果你有一个函数如下，那么你最好写一些注释

public string GetRequestFile(){
    if(String.IsNullOrEmpty(Request.QueryString["fileName"]))
    return magicFileName;//你可能需要说明为什么会返回这样一个文件名
     normal procedure....
}

。

      第二、为什么我不写注释。首先我面对的是专业的人员，大家都是做软件的，没有可能看不懂。其次，现在项目的语言是C#，面向对象的，具有很好的封装性，一个类的代码行数不会很多（因为职责单一）。最后函数和类是自说明的是比较简小的，理解起来也没有什么困难（我写的函数一般不超过10行，如果异常处理多一点也就20行，函数名和类名也符合规范，类一般不超过150行）。

      第三、为什么会要求注释。1、程序写的很不好，函数和类名没有自说明（或者由于语言导致的，比如C）。2、代码阅读人员对业务不熟悉（建议先熟悉业务，因为业务是根本，技术只是实现而已）。3、代码阅读人员能力有限或者自身的经历导致了需要由注释看起。

      而要求我写注释的人属于第三的3。他本身是由PHP转过来的，而且其代码风格是纯粹的面向过程的，写的程序很多注释，但是也很长，经常一个页面下来也就1两个函数搞定，300行是家常便饭。因此他阅读程序养成了一个很不好的习惯的就是总是要全部把程序看完，才可以理清楚这个类是做什么的（类名和函数名对他来说都是浮云，GetRequestFile和GetResponeFile对他应该没有什么区别）。而很多时候我们看代码，第一个就是看类名，其次就是看被调用的函数的名称（公共方法），一般情况下，已经足够判断这个类是做什么的，还有提供的什么功能（如果不行，你可以跟类的作者说，重构一下吧，哥看得苦）。这里就要求我们写代码的时候要像写诗一样去写，就算不行，起码也要做到代码的自解释。因此如果你也是一个拒绝写注释的人，那么你写的代码满足第一和第二吗？

      最后被要求注释的类大概是这样的。

 

class UserAuth{
    public bool UserLoginAsClient(){
          ......
    }
    public bool UserLoginAsManager(){
          ......
    }

    another private function
}

 

转载于:https://www.cnblogs.com/hrmai/archive/2011/05/14/2046043.html