一、java的三種注釋類型
- 單行注釋:// ......
- 塊注釋:/* ...... */
- 文檔注釋:/** ...... */
二、指導原則
- 注釋不能美化糟糕的代碼,碰到糟糕的代碼就重新寫吧。
- 用代碼來闡述你的意圖,好的代碼就是最好的注釋。
- 錯誤的注釋比不注釋更可怕。
- 大括號后不要加注釋,建議另起一行。
- 注釋調的代碼建議刪掉。
- 廢話式注釋,循規式注釋,誤導性注釋都應該刪掉。
- 巧用標記(TODO、FIXME)
- 注釋要放在距離其描述代碼最近的位置。
三、代碼格式列舉
這里和大家聊下代碼基本格式,好的代碼格式會讓維護者更容易閱讀和理解。
package effective.code.up;
/**
*
* <p>Description: 這里寫出這個類的描述,新寫的類一定要帶上日期和作者</p>
* @author wudiffs
* @date 2019年5月7日
*/
public class EffectiveCodeFormat {
public static void main(String[] args) {
// 縮進4個空格
String say = "hello";
// 運算符左右必須有一個空格
int flag = 0;
// 關鍵詞if與括號之間必須有一個空格,括號內的f與左括號,0與右括號不需要空格
if (flag == 0) {
System.out.println(say);
}
// 左大括號前加空格且不換行,左大括號后換行
if (flag == 1) {
System.out.println("world");
// 右大括號前換行,右大括號有else,不用換行
} else {
System.out.println("ok");
// 在右大括號直接結束,則必須換行
}
/*當行字符數限制不超過120個字符,超出需換行,換行遵循如下原則:
* 1.第二行相對第一行縮進4個空格,從第三行開始,不再繼續縮進
* 2.運算符與上下文一起換行
* 3.方法調用的點符號與下文一起換行
* 4.方法調用多個參數,需要換行時,在逗號后進行
* 5.括號前不要換行
*/
StringBuffer sb = new StringBuffer();
sb.append("AA").append("AA").append("AA").append("AA").append("AA").append("AA").append("AA").append("AA")
.append("BB").append("BB").append("BB").append("BB").append("BB").append("BB").append("BB").append("BB")
.append("BB").append("BB").append("BB").append("BB");
// 不同邏輯,不同語義,不同業務的代碼之間插入一個空行分隔開來以提升可讀性。
System.out.println("six six six up up up");
}
/**
* 方法參數在定義和傳入時,多個參數逗號后邊必須加空格。方法描述要加上。
* @param sa
* @param sb
* @param sc
*/
public static void doSomething(String sa, String sb, String sc) {}
}