代碼注釋和格式化的 10 個最佳實踐

代碼注釋和格式化的目的都是為了讓代碼更容易閱讀和了解，提升了代碼的可維護性，下面是 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) //(?!?)

不要編寫錯誤的注釋，比無注釋更可惡 為非常重要的變量編寫注釋，而不是使用自文檔風格 為所有的公開的方法和接口編寫注釋，這是必須的 應該删除文檔中一些無用的内容，例如 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

英文原文， OSCHINA原創翻譯

轉載于:https://www.cnblogs.com/luxiaofeng54/archive/2012/03/23/2413268.html