開心一笑
【今天朋友當(dāng)著我們的面甩一張卡給他媳婦随静，說隨便刷，我們心想他何時(shí)變得這么man吗讶，只見他媳婦甩起卡就往他臉上扔燎猛，說：“有脾氣給信用卡，給我什么公交卡”照皆。我們在一旁笑爆了重绷！神回復(fù)：他的意思應(yīng)該是讓媳婦有多遠(yuǎn)滾多遠(yuǎn)吧？】
提出問題
如何寫出優(yōu)雅的注釋???
解決問題
優(yōu)雅的注釋
溫習(xí)Java的三種類型注釋
Java提供3中類型的注釋膜毁，具體如下：
- 單行注釋(single-line) ：短注釋 //……
- 塊注釋(block) ：多行注釋 /……/
- 文檔注釋(javadoc)：注釋若干行昭卓，并寫入javadoc文檔 /*……/
程序清單 1-1
/**
* 我是文檔注釋，除了可以注釋下面方法作用瘟滨，
* 還可以用來自動(dòng)生成文檔
* @author 阿毅
* @date 2017/02/06
*/
@Test
public void test(){
//我是單行注釋,用于短注釋
System.out.println("單行注釋");
/* 我是多行注釋候醒，如果注釋內(nèi)容太多，
一行放不下杂瘸，就使用我 */
System.out.println("多行注釋");
}
注釋需要死記的3句名言
1.代碼即注釋火焰，真正好的注釋就是考慮不用寫注釋,注釋就是一種失敗。 ——《clean code》
2.錯(cuò)誤的注釋比不注釋更可怕胧沫。
3.沒用的注釋生命力是很頑強(qiáng)的昌简。如果不刪掉，我想绒怨，將來你們的軟件部署到月球上纯赎，它們還神一般的存在。 ——《編寫高質(zhì)量代碼：改善Java程序的151個(gè)建議》
兩種單行注釋的困難抉擇
我們先看下面的例子：
程序清單 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();//兩種注釋的比較
}
上面的注釋都是廢話注釋南蹂，只是為了方便舉例犬金。從上面代碼可以看出，如果某一行的代碼特別長六剥，把注釋放在代碼后面就顯得很不合適了晚顷。所有個(gè)人的建議是：使用第一種寫法。具體原因有3點(diǎn)：
- 先看注釋再看代碼比先看代碼再看注釋疗疟，能更快理解代碼含義该默，節(jié)省時(shí)間。
- 第一種注釋不用擔(dān)心代碼過長造成閱讀不方便策彤。
- 如果需要注釋的內(nèi)容比較多栓袖，第一種注釋不用擔(dān)心注釋內(nèi)容過多造成代碼過長匣摘。
綜上所述，我更建議使用第一種注釋裹刮。
括號(hào)后的注釋
在括號(hào)后面寫注釋音榜，看起來不直觀，而且代碼可讀性也不高捧弃，建議另起一行赠叼。具體如下：
程序清單 2-1
@Test
public void test(){
boolean flag = true;
if(flag){//錯(cuò)誤注釋:flag狀態(tài)的轉(zhuǎn)換
flag = false;
}else{
flag = true;
}
try{//錯(cuò)誤注釋
......
}catch (Exception e){//錯(cuò)誤注釋
}
//正確注釋:flag狀態(tài)的轉(zhuǎn)換
if(flag){
flag = false;
}else{
flag = true;
}
}
無情刪掉注釋掉的代碼
項(xiàng)目開發(fā)中，開發(fā)人員經(jīng)常會(huì)把代碼注釋掉违霞，接手人員又不知道該注釋的代碼是否還有用梅割。于是被注釋的代碼就像幽靈一樣，緊緊的纏著項(xiàng)目葛家。它們的生命力無比強(qiáng)大户辞，估計(jì)有一天你們的項(xiàng)目賣到月球上去，注釋代碼還存在癞谒。如果它真的有用底燎，就不會(huì)被注釋掉，無情的刪掉它吧弹砚！抱著不是你死双仍，就是它亡的決心。
程序清單 2-1
@Test
public void test(){
//String s = "該變量沒有用處";
//List<String> list = new ArrayList<>();
System.out.println("上面的變量s和集合list沒有任何用處桌吃，無情刪除吧");
System.out.println("結(jié)束");
}
TODO注釋的妙用
開發(fā)過程中朱沃，時(shí)常因?yàn)楣て谮s而沒有時(shí)間寫好代碼。每個(gè)開發(fā)人員都有意識(shí)茅诱，這個(gè)功能以后要重構(gòu)或優(yōu)化逗物，但往往之后就不了了之了。一個(gè)有用的注釋就是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)化
}
}
單行注釋和多行注釋不要混用
雖然多行注釋可以嵌套單行注釋摆寄，但是我們不建議你這樣混合用失暴，具體實(shí)例如下：
程序清單 2-1
@Test
public void test(){
/*這里是多行注釋，可以嵌套單行注釋
//這里是單行注釋
*/
System.out.println("多行注釋可以嵌套單行注釋");
/*這里是多行注釋
/*
這里也是多行注釋微饥，但是多行注釋不能嵌套多行注釋
*/
*/
System.out.println("多行注釋不能嵌套多行注釋");
}
總結(jié)：錯(cuò)誤注釋是一種傷害逗扒，必要注釋是一種責(zé)任,不注釋便是一種境界。
避免廢話式注釋
不要嚴(yán)重低估代碼閱讀者的智商欠橘，對于一些廢話式的注釋矩肩，應(yīng)該極力避免。具體事例如下：
程序清單 2-1
/**
* 測試類
* @author 阿毅
* @date 2017/2/7.
*/
public class AyTest {
private int num;
//年份,默認(rèn)值為0(廢話式注釋)
private int year;
//設(shè)置數(shù)量（廢話式注釋2）
public void setNum(int num) {
this.num = num;
}
@Test
public void test(){
//數(shù)量自增（廢話式注釋3）
num ++;
//如果num大于0简软，打印相關(guān)信息（廢話式注釋4）
if(num > 0){
System.out.println("num 大于0");
}else{
System.out.println("num 小于0");
}
}
}
時(shí)刻保持注釋與代碼的同步
由于需求的變化蛮拔，開發(fā)者經(jīng)常會(huì)修改相關(guān)的業(yè)務(wù)代碼，但往往忘記同步修改相關(guān)的業(yè)務(wù)注釋痹升，造成業(yè)務(wù)注釋和業(yè)務(wù)代碼完全不沾邊建炫。所有在項(xiàng)目開發(fā)中，我們要時(shí)刻保持注釋與代碼的同步疼蛾。修改了代碼肛跌，頭腦馬上要想起來修改相關(guān)的注釋。
代碼注釋察郁，代碼注釋衍慎，代碼注釋，重要事情說3遍
讀書感悟
來自《納尼亞傳奇》
- When you choose to become others, you will lose yourself.
當(dāng)你選擇成為別人皮钠，你將失去你自己. - 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.
經(jīng)典故事
【小雞問母雞：可否不用下蛋，帶我出去玩翱钋帧末荐？母雞道：不行，我要工作新锈！小雞說：可你已經(jīng)下了這么多蛋了甲脏！母雞意味深長地對小雞說：一天一個(gè)蛋，菜刀靠邊站妹笆，一月不生蛋块请，高壓鍋里見。
存在是因?yàn)槟銊?chuàng)造價(jià)值拳缠，淘汰是因?yàn)槟闶r(jià)值负乡。過去的價(jià)值不代表未來，所以每天都要努力脊凰！】
大神文章
[1] Robert C.Martin. Clean Code: A Handbook of Agile Software [M]. Prentice Hall PTR,2008:50-69
[2] 秦小波. 編寫高質(zhì)量代碼：改善Java程序的151個(gè)建議[M]. 北京：機(jī)械工業(yè)出版社抖棘，2012：300-301
其他
如果有帶給你一絲絲小快樂，就讓快樂繼續(xù)傳遞下去狸涌，歡迎點(diǎn)贊切省、頂、歡迎留下寶貴的意見帕胆、多謝支持朝捆！
