关闭

代码注释和格式化的10个最佳实践

185人阅读 评论(0) 收藏 举报

代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 10 个关于代码注释和格式的 10 个最佳实践(特别是 Java)。


代码注释

注释是代码的一部分,在统计代码行时注释也包含在内,非常重要。一段无任何注释的代码很可能是完全无用。尽管有些极端的建议说代码应该有自注释的方法,不过我们还是建议注释良好代码的必要条件。

  1. 只在需要的时候编写注释
    • 不要为每行代码都编写注释,无用而且降低可读性,例如:
      • int count = 0; // 给 count 变量设置初始值,这人人都能看懂 (?!?)
    • 缺少注释会增加代码维护难度和实践,首先变量和方法名应该是可理解和自注释的,下面是两个不好的例子:
      • int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)
        List<int> getVal(int val, int len, String op) //(?!?)
  2. 不要编写错误的注释,比无注释更可恶
  3. 为非常重要的变量编写注释,而不是使用自文档风格
  4. 为所有的公开的方法和接口编写注释,这是必须的
  5. 应该删除文档中一些无用的内容,例如 todo 之类的


代码格式化

很多的开发工具都提供代码格式化的功能,例如 maven checkstyle ,并且这些格式化操作可在代码保存时自动进行,但这些工具格式化的规则多少跟每个公司的要求不同,所以在使用前应该进行设置以便跟公司代码格式规范一致。

下面是一些对于代码格式化的建议:

  1. 统一使用括号的方式:你可以在同一行使用括号或者换一个新行,这都没关系,关键是要一致。
  2. 统一空行使用的规则,例如方法结束后可以来三个空行,是否每行代码都用空行隔开或者不,这些依照自身的习惯而行,但要统一。
  3. 缩进的处理方式统一
  4. 每行的字符数应该有所限制,提升代码可读性,一般 80 左右个字符最为合适
  5. 代码中的空格使用要一致,例如:
    • 操作符和变量:
      • a += b , c = 0; (a == b)
    • 语句和括号之间:
      • if (value) {, public class A { 
    • 循环之中:
      • for (int i = 0; i < length; i++) 
    • 类型转换:
      • (int) value , (String) value
0
0
查看评论

代码注释和格式化的 10 个最佳实践

代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 10 个关于代码注释和格式的 10 个最佳实践(特别是 Java)。 代码注释 注释是代码的一部分,在统计代码行时注释也包含在内,非常重要。一段无任何注释的代码很可能是完全无用。尽管有些极端的建议说代码应该有...
  • tywali
  • tywali
  • 2012-03-22 10:05
  • 167

Java异常处理的10个最佳实践

异常处理在编写健壮的 Java 应用中扮演着非常重要的角色。异常处理并不是功能性需求,它需要优雅地处理任何错误情况,比如资源不可用、非法的输入、null 输入等等。Java 提供很多异常处理特性,通过内置的 try、catch、finally关键字实...
  • u011192409
  • u011192409
  • 2016-06-14 14:44
  • 542

10 个代码注释及格式化的最佳实践

代码注释及格式化关乎代码的可读性,而代码可读性对于代码可维护性又是至关重要的,因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。 一、注释 注释是代码的一部分,其重要性显而易见。缺少注释的代码可以说是没有用的,虽然有人建议使用自文档化代码,不过...
  • u011251014
  • u011251014
  • 2015-11-10 20:45
  • 407

IOS代码注释小结

代码注释的必要性:想想看,半年之前代码,如果没有注释,是什么结果,擦,谁写的,写的啥?。。。好像是我写的。。 减少同事之间的沟通成本 快速恢复代码记忆 快速生成文档 注释的形式形式A: /// Single line comment./// Single line comme...
  • tskyming
  • tskyming
  • 2015-06-05 16:50
  • 1088

代码注释格式化

注释格式化
  • zlf_jack
  • zlf_jack
  • 2014-09-27 11:07
  • 1172

单行注释、多行注释、文档注释最完美的解释、导出API

注释是程序开发人员和程序阅读者之间交流的手段,对代码的解释和说明,提高软件的可读性,有利于程序应用的维护。 1、单行注释  只对一行代码注释,例如 //单行注释,以‘//’开头,跟在‘//’后面的文本就是注释内容。单行注释不会被编译,不要把代码写在‘//’的后面。  快捷键...
  • qq_30908729
  • qq_30908729
  • 2017-08-12 14:00
  • 699

10个最“牛叉”的代码注释

你看到过的最好的代码注释是什么样的?看看这些够不够牛!
  • wdcxylg
  • wdcxylg
  • 2016-03-16 23:31
  • 338

Java异常处理手册和最佳实践

Java异常处理框架是非常强大并且很容易理解和使用,异常可能产生于不同的情况,例如:用户错误数据的输入,硬件故障,网络连接失败,数据服务器故障等等,下面我们需要学习在java中如何处理这些异常。在程序执行的时候,无论什么时候产生错误,都会创建一个Exception对象并且正常的程序流也会中断,JRE...
  • hp910315
  • hp910315
  • 2015-10-21 15:26
  • 2899

10个最“优秀”的代码注释

下面是stackoverflow网站上网友针对你看到过的最好的代码注释是什么样的?这个问题给出的回答的前10条: // 亲爱的维护者: // 如果你尝试了对这段程序进行‘优化’, // 并认识到这种企图是大错特错,请增加 // 下面这个计数器的个数,用来对后来人进行警告: // 浪费在这里...
  • gaoenjoy
  • gaoenjoy
  • 2014-08-25 16:50
  • 170

Shell编程的10个最佳实践

每一个在UNIX/Linux上工作的程序员可能都擅长shell脚本编程。 但大家解决问题的方式却不尽相同,这要取决于对专业知识的掌握程度、使用命令的种类、看待问题的方式等等。对于那些处在shell脚本编程初级阶段的程序员来说,遵循一些恰当的做法可以帮助你更快、更好的学习这些编程技巧。下面,我们就来讨...
  • jb19900111
  • jb19900111
  • 2014-01-02 14:26
  • 524
    个人资料
    • 访问:27746次
    • 积分:465
    • 等级:
    • 排名:千里之外
    • 原创:1篇
    • 转载:71篇
    • 译文:0篇
    • 评论:0条
    文章分类