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

fmms 11年前
     代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 10 个关于代码注释和格式的 10 个最佳实践(特别是 Java)。    <p></p>    <p><b>代码注释</b></p>    <p>注释是代码的一部分,在统计代码行时注释也包含在内,非常重要。一段无任何注释的代码很可能是完全无用。尽管有些极端的建议说代码应该有自注释的方法,不过我们还是建议注释良好代码的必要条件。</p>    <ol>     <li><span style="text-align:justify;font-family:'Trebuchet MS', sans-serif;">只在需要的时候编写注释</span></li>     <ul>      <li>不要为每行代码都编写注释,无用而且降低可读性,例如:</li>      <ul>       <li>int count = 0; // 给 count 变量设置初始值,这人人都能看懂 (?!?)</li>      </ul>      <li>缺少注释会增加代码维护难度和实践,首先变量和方法名应该是可理解和自注释的,下面是两个不好的例子:</li>      <ul>       <li>int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)</li>       <li>List<int> getVal(int val, int len, String op) //(?!?)</li>      </ul>     </ul>     <li>不要编写错误的注释,比无注释更可恶</li>     <li>为非常重要的变量编写注释,而不是使用自文档风格</li>     <li>为所有的公开的方法和接口编写注释,这是必须的</li>     <li>应该删除文档中一些无用的内容,例如 todo 之类的</li>    </ol>    <p><b>代码格式化</b></p>    <p>很多的开发工具都提供代码格式化的功能,例如 <a href="/misc/goto?guid=4958334084110965956" rel="nofollow">maven checkstyle</a> ,并且这些格式化操作可在代码保存时自动进行,但这些工具格式化的规则多少跟每个公司的要求不同,所以在使用前应该进行设置以便跟公司代码格式规范一致。</p>    <p>下面是一些对于代码格式化的建议:</p>    <ol>     <li>统一使用括号的方式:你可以在同一行使用括号或者换一个新行,这都没关系,关键是要一致。</li>     <li>统一空行使用的规则,例如方法结束后可以来三个空行,是否每行代码都用空行隔开或者不,这些依照自身的习惯而行,但要统一。</li>     <li>缩进的处理方式统一</li>     <li>每行的字符数应该有所限制,提升代码可读性,一般 80 左右个字符最为合适</li>     <li>代码中的空格使用要一致,例如:</li>     <ul>      <li><span style="text-align:justify;font-family:'Trebuchet MS', sans-serif;">操作符和变量:</span></li>      <ul>       <li><span>a += b , c = 0; (a == b)</span></li>      </ul>      <li><span style="text-align:justify;font-family:'Trebuchet MS', sans-serif;">语句和括号之间:</span></li>      <ul>       <li><span>if (value) {, public class A { </span></li>      </ul>      <li><span style="text-align:justify;font-family:'Trebuchet MS', sans-serif;">循环之中:</span></li>      <ul>       <li><span>for (int i = 0; i < length; i++) </span></li>      </ul>      <li><span style="text-align:justify;font-family:'Trebuchet MS', sans-serif;">类型转换:</span></li>      <ul>       <li><span>(int) value , (String) value</span></li>      </ul>     </ul>    </ol>    <a href="/misc/goto?guid=4958334084921067342" rel="nofollow" target="_blank">英文原文</a>, OSCHINA原创翻译