歡迎您光臨本站 註冊首頁

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

←手機掃碼閱讀     火星人 @ 2014-03-12 , reply: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

英文原文, OSCHINA原創翻譯



[火星人 ] 代碼註釋和格式化的 10 個最佳實踐已經有320次圍觀

http://coctec.com/docs/program/show-post-71372.html