開心一笑
【今天朋友當著我們的面甩一張卡給他媳婦，說隨便刷，我們心想他何時變得這么man，只見他媳婦甩起卡就往他臉上扔，說：“有脾氣給信用卡，給我什么公交卡”。我們在一旁笑爆了！神回復：他的意思應該是讓媳婦有多遠滾多遠吧？】
提出問題
如何寫出優(yōu)雅的注釋???
解決問題
優(yōu)雅的注釋
溫習Java的三種類型注釋
Java提供3中類型的注釋，具體如下：
- 單行注釋(single-line) ：短注釋 //……
- 塊注釋(block) ：多行注釋 /……/
- 文檔注釋(javadoc)：注釋若干行，并寫入javadoc文檔 /*……/
程序清單 1-1
/**
* 我是文檔注釋，除了可以注釋下面方法作用，
* 還可以用來自動生成文檔
* @author 阿毅
* @date 2017/02/06
*/
@Test
public void test(){
//我是單行注釋,用于短注釋
System.out.println("單行注釋");
/* 我是多行注釋，如果注釋內容太多，
一行放不下，就使用我 */
System.out.println("多行注釋");
}
注釋需要死記的3句名言
1.代碼即注釋，真正好的注釋就是考慮不用寫注釋,注釋就是一種失敗。 ——《clean code》
2.錯誤的注釋比不注釋更可怕。
3.沒用的注釋生命力是很頑強的。如果不刪掉，我想，將來你們的軟件部署到月球上，它們還神一般的存在。 ——《編寫高質量代碼：改善Java程序的151個建議》
兩種單行注釋的困難抉擇
我們先看下面的例子：
程序清單 2-1
/**
* 描述:比較注釋的使用方法
* @author 阿毅
* @date 2017/02/06
*/
@Test
public void test(){
//第一種寫法：注釋放在代碼上面
//打印ay
System.out.println("Ay");
//打印and
System.out.println("and");
//打印al
System.out.println("Al");
//第二種寫法：注釋放在代碼后面
System.out.println("Ay");//打印ay
System.out.println("and");//打印and
System.out.println("Al");//打印al
//兩種注釋優(yōu)劣的比較
Collections.EMPTY_LIST.stream().filter(entry -> entry.toString().equals("a")).count();//兩種注釋的比較
}
上面的注釋都是廢話注釋，只是為了方便舉例。從上面代碼可以看出，如果某一行的代碼特別長，把注釋放在代碼后面就顯得很不合適了。所有個人的建議是：使用第一種寫法。具體原因有3點：
- 先看注釋再看代碼比先看代碼再看注釋，能更快理解代碼含義，節(jié)省時間。
- 第一種注釋不用擔心代碼過長造成閱讀不方便。
- 如果需要注釋的內容比較多，第一種注釋不用擔心注釋內容過多造成代碼過長。
綜上所述，我更建議使用第一種注釋。
括號后的注釋
在括號后面寫注釋，看起來不直觀，而且代碼可讀性也不高，建議另起一行。具體如下：
程序清單 2-1
@Test
public void test(){
boolean flag = true;
if(flag){//錯誤注釋:flag狀態(tài)的轉換
flag = false;
}else{
flag = true;
}
try{//錯誤注釋
......
}catch (Exception e){//錯誤注釋
}
//正確注釋:flag狀態(tài)的轉換
if(flag){
flag = false;
}else{
flag = true;
}
}
無情刪掉注釋掉的代碼
項目開發(fā)中，開發(fā)人員經常會把代碼注釋掉，接手人員又不知道該注釋的代碼是否還有用。于是被注釋的代碼就像幽靈一樣，緊緊的纏著項目。它們的生命力無比強大，估計有一天你們的項目賣到月球上去，注釋代碼還存在。如果它真的有用，就不會被注釋掉，無情的刪掉它吧！抱著不是你死，就是它亡的決心。
程序清單 2-1
@Test
public void test(){
//String s = "該變量沒有用處";
//List<String> list = new ArrayList<>();
System.out.println("上面的變量s和集合list沒有任何用處，無情刪除吧");
System.out.println("結束");
}
TODO注釋的妙用
開發(fā)過程中，時常因為工期趕而沒有時間寫好代碼。每個開發(fā)人員都有意識，這個功能以后要重構或優(yōu)化，但往往之后就不了了之了。一個有用的注釋就是TODO注釋，具體如下：
程序清單 2-1
@Test
public void test(){
List<String> userIds = new ArrayList<>();
for(int i=0;i<userIds.size();i++){
//廢話注釋：通過id查找用戶（只是為了說明方便）
User user = userService.findById(userIds.get(i));
//TODO 由于工期短，在for循環(huán)中查詢數(shù)據(jù)庫數(shù)據(jù)，后期必須優(yōu)化
}
}
單行注釋和多行注釋不要混用
雖然多行注釋可以嵌套單行注釋，但是我們不建議你這樣混合用，具體實例如下：
程序清單 2-1
@Test
public void test(){
/*這里是多行注釋，可以嵌套單行注釋
//這里是單行注釋
*/
System.out.println("多行注釋可以嵌套單行注釋");
/*這里是多行注釋
/*
這里也是多行注釋，但是多行注釋不能嵌套多行注釋
*/
*/
System.out.println("多行注釋不能嵌套多行注釋");
}
總結：錯誤注釋是一種傷害，必要注釋是一種責任,不注釋便是一種境界。
避免廢話式注釋
不要嚴重低估代碼閱讀者的智商，對于一些廢話式的注釋，應該極力避免。具體事例如下：
程序清單 2-1
/**
* 測試類
* @author 阿毅
* @date 2017/2/7.
*/
public class AyTest {
private int num;
//年份,默認值為0(廢話式注釋)
private int year;
//設置數(shù)量（廢話式注釋2）
public void setNum(int num) {
this.num = num;
}
@Test
public void test(){
//數(shù)量自增（廢話式注釋3）
num ++;
//如果num大于0，打印相關信息（廢話式注釋4）
if(num > 0){
System.out.println("num 大于0");
}else{
System.out.println("num 小于0");
}
}
}
時刻保持注釋與代碼的同步
由于需求的變化，開發(fā)者經常會修改相關的業(yè)務代碼，但往往忘記同步修改相關的業(yè)務注釋，造成業(yè)務注釋和業(yè)務代碼完全不沾邊。所有在項目開發(fā)中，我們要時刻保持注釋與代碼的同步。修改了代碼，頭腦馬上要想起來修改相關的注釋。
代碼注釋，代碼注釋，代碼注釋，重要事情說3遍
讀書感悟
來自《納尼亞傳奇》
- When you choose to become others, you will lose yourself.
當你選擇成為別人，你將失去你自己. - I focus too much on what I lost, not what I have.
我太專注于我所失去的，忽略了我所擁有的. - You are nothing if you don’t believe！
如果沒有信心，你就什么都不是！ - 你愿意和我并肩作戰(zhàn)嗎? Are you with me ?
至死不渝! To the death.
經典故事
【小雞問母雞：可否不用下蛋，帶我出去玩??？母雞道：不行，我要工作！小雞說：可你已經下了這么多蛋了！母雞意味深長地對小雞說：一天一個蛋，菜刀靠邊站，一月不生蛋，高壓鍋里見。
存在是因為你創(chuàng)造價值，淘汰是因為你失去價值。過去的價值不代表未來，所以每天都要努力！】
大神文章
[1] Robert C.Martin. Clean Code: A Handbook of Agile Software [M]. Prentice Hall PTR,2008:50-69
[2] 秦小波. 編寫高質量代碼：改善Java程序的151個建議[M]. 北京：機械工業(yè)出版社，2012：300-301
其他
如果有帶給你一絲絲小快樂，就讓快樂繼續(xù)傳遞下去，歡迎點贊、頂、歡迎留下寶貴的意見、多謝支持！
