程序代码注释的规范与建议

你的代码注释到位了吗?
服务器君一共花费了363.513 ms进行了7次数据库查询,努力地为您提供了这个页面。
试试阅读模式?希望听取您的建议
  1. Comment each level
  2. 对每一级用统一的方法注释每个代码块,例如:

    • 为每个类,包含简短的描述,作者和最后修改日期
    • 为每个方法,包含其目的,功能,参数,返回值

    团队编程时,采用标准的注释是很重要的。当然,采用代码协定和工具(比如c#中的XML和java中的Javadoc)帮助这项工作也是可接受的,甚至更可取。

  3. Use paragraph comments
  4. 将代码块分成多个片段,每个片段执行一个简单的任务,然后在每个片段前添加注释,引导读者即将发生什么。

    // Check that all data records
    // are correct 
    foreach (Record record in records) 
    {
        if (rec.checkStatus()==Status.OK)
        { 
            ......
        } 
    } 
    // Now we begin to perform 
    // transactions 
    Context ctx = new ApplicationContext(); 
    ctx.BeginTransaction();
    ......
    
  5. Align comments in consecutive lines
  6. 对于多行且每行后都紧跟着注释的情况,我们应该排列这些注释,使它们更易读懂。

    const MAX_ITEMS = 10; // maximum number of packets 
    const MASK = 0x1F;    // mask bit TCP
    

    一些开发人员用Tab来排列注释,其他的则用空格。最佳途径还是用空格,因为在各种编辑器和IDE中,tab键的行为多种多样。

  7. Don’t insult the reader’s intelligence
  8. 避免显然的注释,比如:

    if (a == 5)      	// if a equals 5 
    	counter = 0; 	// set the counter to zero
    

    这既浪费时间写不必要的注释,又使读者分心,因为这些细节读者很容易从你的代码中推断出来。

  9. Be polite
  10. 避免粗鲁的注释,比如“Notice the stupid user has entered a negative number,”或“This fixes the side effect produced by the pathetically inept implementation of the initial developer”。此类注释很难在他们的程序代码中得到好的效果,并且你甚至不知道以后谁会读这种注释,你的上司,客户或可怜的愚蠢的新手。

  11. Get to the point
  12. 不要写无关你要传达意思的注释。避免笑话,诗歌和赘言。简而言之,保持注释简洁,直接。

  13. Use a consistent style
  14. 一些人认为注释应该写的让非程序员也能明白,其他人则认为只对程序员即可。无论如何,作为成功的代码注释策略,应该是一致的以及总是面向相同的读者。个人意见,我甚至怀疑很多非程序员是否会读代码,所以注释应面向程序员。

  15. Use special tags for internal use
  16. 团队开发时,采用一致的一套标签作为程序员间的沟通。比如,很多团队使用“TODO:”标签来指出需要附加编写的代码段:

    int Estimate(int x, int y) 
    {
        // TODO: implement the calculations 
        return 0;
    }
    

    标签注释并不解释代码,它们往往寻求注意或传递信息。但是,如果你用这种方法,务必将你要传递的信息写上。

  17. Comment code while writing it
  18. 在编写代码是添加注释,此时它们在你脑中还是清晰的。如果你直到最后才来添加,将事倍功半。“I have no time to comment“,”I’m in a hurry”和“the project is delayed”都是简单的借口而阻止代码中写文档。一些开发人员认为你应该在编写代码前写注释作为一种筹划最终方案的途径。举例:

    public void ProcessOrder() 
    {
        // Make sure the products are available
        // Check that the customer is valid 
        // Send the order to the store 
        // Generate bill 
    }
    
  19. Write comments as if they were for you(in fact,they are)
  20. 注释代码时,不仅仅要考虑其他开发人员以后可能会维护你的代码,也要考虑你自己。 伟大的Phil Haack曾说过:"As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."

    结果,我们自己将是优良(笨拙)注释的第一个受益(害)者。

  21. Update comments when you update the code
  22. 如果注释没有随着代码更新,那样的注释不能保证正确。代码和注释必须同步修改,否则你的注释将使维护你代码的开发人员的工作很难做。特别要注意重构工具自动的更新了你的代码而没有改变你的注释的情况,这也将导致同样的结果。

  23. The golden role of comment:readable code
  24. 程序员的基本功之一:让你的代码为自己说话。尽管一些不喜欢写注释的人怀疑这是程序员们瞎编乱造的,不过事实是自明的代码对于编写更易懂的代码甚至使注释变的不必要有很好的帮助。例如,在我的Fluid Interfaces文章中展示了干净自明的代码可能是这样的:

    Calculator calc = new Calculator();
    calc.Set(0);
    calc.Add(10);
    calc.Multiply(2);
    calc.Subtract(4);
    Console.WriteLine( "Result: {0}", calc.Get() );
    

    在这个例子里,注释是不需要的而且那样做可能会与第4条相违背。为了写出更易读的代码,你可能要考虑使用合适的命名方式(Stringer’s Rules),确保正确的缩排和采用代码样式指南。不遵守这条提示的结果可能是注释看起来象似向糟糕的代码道歉。

  25. Share these tips with your colleagues
  26. 尽管我们在第10条中指出我们自己是怎样立即从优良的注释的受益的,但是这些条款对所有开发人员都有用,尤其是团队开发。因此,请将这些注释条款与你的同事分享,一起写易懂和易维护的代码。

本文地址:http://www.nowamagic.net/librarys/veda/detail/725,欢迎访问原出处。

不打个分吗?

转载随意,但请带上本文地址:

http://www.nowamagic.net/librarys/veda/detail/725

如果你认为这篇文章值得更多人阅读,欢迎使用下面的分享功能。
小提示:您可以按快捷键 Ctrl + D,或点此 加入收藏

大家都在看

阅读一百本计算机著作吧,少年

很多人觉得自己技术进步很慢,学习效率低,我觉得一个重要原因是看的书少了。多少是多呢?起码得看3、4、5、6米吧。给个具体的数量,那就100本书吧。很多人知识结构不好而且不系统,因为在特定领域有一个足够量的知识量+足够良好的知识结构,系统化以后就足以应对大量未曾遇到过的问题。

奉劝自学者:构建特定领域的知识结构体系的路径中再也没有比学习该专业的专业课程更好的了。如果我的知识结构体系足以囊括面试官的大部分甚至吞并他的知识结构体系的话,读到他言语中的一个词我们就已经知道他要表达什么,我们可以让他坐“上位”毕竟他是面试官,但是在知识结构体系以及心理上我们就居高临下。

所以,阅读一百本计算机著作吧,少年!

《浪潮之巅》 吴军 (作者)

近一百多年来,总有一些公司很幸运地、有意识或无意识地站在技术革命的浪尖之上。在长达十年甚至几十年的时间里,它们代表着科技的浪潮,直到下一波浪潮的来临。从19世纪末算起,AT&T公司、IBM公司、苹果公司、英特尔公司、微软公司、思科公司、雅虎公司和Google公司都先后被幸运地推到了浪尖。虽然,它们来自不同的领域,中间有些已经衰落或正在衰落,但是它们都极度辉煌过。吴军的这本《浪潮之巅》系统地介绍了这些公司成功的本质原因及科技工业一百多年的发展。在这些公司兴衰的背后,有着它必然的规律。《浪潮之巅》不仅讲述科技工业的历史,更重在揭示它的规律性。

更多计算机宝库...