英文原文：10 Best Practices of Code Commenting & Formatting 代码注释和格式化的目的都是为了让代码更容易阅读和理解，提升了代码的可维护性，下面是 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

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接。 2KB翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

2KB项目（www.2kb.com，源码交易平台）,提供担保交易、源码交易、虚拟商品、在家创业、在线创业、任务交易、网站设计、软件设计、网络兼职、站长交易、域名交易、链接买卖、网站交易、广告买卖、站长培训、建站美工等服务