熱度資訊

• 熱門度 29
• 發文
• 時間 2024-12-25 21:04:14

          
以下是根據本魯碼農自己的經驗，絕大部份參考Clean Code這本書，我自己是將這本書奉為
圭臬，不過我也知道很多人反對書裡的一些看法，所以聽聽就好


首先一個最大的原則就是程式碼必須好懂，因為它同時是寫給機器跟人看的，好懂是可擴充
性跟可維護性的必要，是程式碼無比重要的基石

推文有人說程式碼沒有註解的話十年後的自己會無法理解，實際上根據我自己的經驗如果我
寫出一段不好讀的程式碼，幾天、幾個小時甚至幾分鐘之後我就會痛恨之前的自己了

那麼註解是必要的嗎？我認為註解有其必要，但應該越少越好

為什麼越少越好呢？首先，程式碼應該要可以自己描述自己，來看一個簡單的範例：

float multi(float a, float b) {
    return a*b;
}

很容易就能看出這是一個做乘法的方法，但他的用處是什麼？沒人看得出來

float convertUsdToNtd(float usd, float converRatio) {
     return usd * convertRatio;
}

這樣就一目了然了，這是一個把美金轉換成新台幣的方法，如此就不需要註解了。在實務上
，尤其是在有複雜的業務邏輯的時候，變數跟方法名稱可能會長到惱人的地步，但為了可讀
性，這是必要的犧牲。

我們還能繼續擴充這個方法，例如說加入即時匯率，讓他可以將轉換幣值這件事做的更好

float convertUsdToNtd(float usd, FinaceService financeService) {
     return usd * finaceService.getUsdToNtdRatio; // Multiply usd and ratio.
}

上面的程式碼有一行註解，但不難看出這個註解是一句廢話，因為他只是描述了該句程式碼
做了什麼。好的註解應該從抽象、高層次的方向來解釋程式碼的用意、為什麼要這麼寫：

float convertUsdToNtd(float usd, FinaceService financeService) {
    // Fetch ratio from finance service for real time
     return usd * finaceService.getUsdToNtdRatio;
}

上面的程式碼解釋了為什麼要從finance service 獲得匯率，因為必須要獲得當下即時的匯
率

但註解並不總是好的，有時候他可能是有害的。假設我今天修改了這個方法，讓他不再是根
據即時匯率，而是某一天的平均匯率：

float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService)
{
    // Fetch ratio from finance service for real time
     return usd * finaceService.getUsdToNtdRatioByDate(date);
}

程式碼更改但是註解忘了更新的情況下，這行註解就是錯的。錯誤的註解會造成混亂，低效
，甚至錯誤！程式碼本身的可讀性重要性應該永遠高於註解，因為程式碼描述的就是事實，
你沒辦法寫出一行程式碼做的事情和他看起來的不同（Well, 通常沒辦法）但是註解可以！

跟註解不同的是，我認為文件（document）是有必要而且多一點較好的，文件是寫在方法前
面的註解，用來描述這個方法做了什麼：

/*
Convert USD to NTD by ratio from a specific date.
*/
float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService)
{
     return usd * finaceService.getUsdToNtdRatioByDate(date);
}

文件是讓下一份閱讀程式碼的人（通常就是你自己）快速理解這個方法是做什麼，他會輸入
什麼，他會回傳什麼最好的方式。文件只會從最抽象的層次描述方法，不會包含任何的實作
細節，除非這個細節有必要讓使用者知道（例如說，某些情況下的演算法和其時間複雜度）
。而且我認為應該要採用文件導向的方式-當你創建新的方法時，你應該先編寫文件修改時
亦同

※ 引述《ianlin1216 (伊恩可可)》之銘言
: 餓死抬頭
: https://i.imgur.com/3QcIsVN.jpeg
: 本魯不是資工系的啦
: 所以不知道寫程式不加註解會有多嚴重
: 想請問相關從業的鄉民
: 實務上遇到這種情況真的很賭爛嗎
: 乾五西恰