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

转载 2012年03月22日 10:05:25
代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 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

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

代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 10 个关于代码注释和格式的 10 个最佳实践(特别是 Java)。 代码注释 注释是代码的...
  • neo_yin
  • neo_yin
  • 2012年03月27日 15:48
  • 167

10 个 Java 编码中微妙的最佳实践

  • 2013年08月31日 17:40
  • 20KB
  • 下载

【iOS10 SpeechRecognition】语音识别 现说现译的最佳实践

首先想强调一下“语音识别”四个字字面意义上的需求:用户说话然后马上把用户说的话转成文字显示!,这才是开发者真正需要的功能。 做需求之前其实是先谷歌百度一下看有没有造好的轮子直接用,结果真的很呵呵,...

关于 shell 脚本编程的10 个最佳实践

每一个在UNIX/Linux上工作的程序员可能都擅长shell脚本编程。但大家解决问题的方式却不尽相同,这要取决于对专业知识的掌握程度、使用命令的种类、看待问题的方式等等。对于那些处在shell脚本编...
  • rj042
  • rj042
  • 2013年04月24日 11:05
  • 686

10 个项目文档最佳实践

在软件开发和维护过程中,文档是必不可少的资料,它可以提高软件开发的效率,保证软件的质量,而且在软件的使用过程中有指导、帮助、解惑的作用。尤其在维护工作中,文档的重要性更是不言而喻。 本文整理了软...

在Oracle Linux 6.5上安装Oracle 10gR2 的最佳实践【Maclean版】

在Oracle Linux 6.5上安装Oracle 10gR2 的最佳实践【Maclean版】     本安装文档的脚本下载: 在Oracle Linux 6.5上安装Oracle...

Javascript 最佳实践 10 条建议

初级开发人员维护自己开发的产品可能也会是一个噩梦,比如我。过年前写的一个产品因为数据不全的问题一直没有上线,昨天数据库的搞定了,要准备上线了,需要我这边改一下功能,我喵了一眼JS,发现其中一个 dra...

10 个项目文档最佳实践

在软件开发和维护过程中,文档是必不可少的资料,它可以提高软件开发的效率,保证软件的质量,而且在软件的使用过程中有指导、帮助、解惑的作用。尤其在维护工作中,文档的重要性更是不言而喻。 本文整理了软...
  • lgx06
  • lgx06
  • 2012年11月22日 13:04
  • 525
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:代码注释和格式化的 10 个最佳实践
举报原因:
原因补充:

(最多只允许输入30个字)