為什麼需要寫註解？

雖然理想中的 Clean Code 應該具備自我解釋的能力，但實際在開發過程中，撰寫註解仍然是必要的，特別是在協作開發和專案交接的情況中。以下是撰寫註解的主要原因：

1. 團隊協作的溝通橋樑：不同開發者在專案中參與的深度和熟悉度不同，註解可以幫助新成員快速了解專案邏輯，減少溝通成本。
2. 專案交接與維護：當專案轉交給新的開發者時，註解能加速他們理解核心功能和複雜邏輯。
3. 複雜邏輯的解釋：即使是經驗豐富的開發者，在處理複雜的邏輯或演算法時，註解可以明確指出背後的原因和過程，方便日後維護。
4. 提醒 code reviewer：在進行 code review 時，註解能讓審查者迅速理解函數、變數或邏輯的意圖，減少對誤解或錯誤假設的可能性。
5. 記錄業務邏輯：有時候程式碼中的實現方式並非最直觀的技術選擇，而是基於特定的業務需求或外部條件。註解可以幫助後續開發者理解這些決策背後的原因。

提醒

然而，撰寫註解在某些情況下雖然重要，但不應該當作掩飾品質差的程式碼之功用。應該以良好的命名和結構來減少對註解的依賴，但在面對複雜邏輯、特定業務需求或團隊合作時，適當的註解仍然是不可或缺的輔助手段。

什麼時候需要寫註解？

1. 複雜的邏輯：當程式碼中包含複雜的邏輯、算法或流程時，應寫註解來解釋它的運作原理和背後的原因。
2. 不明確的變數或函數：當變數、函數或類別名稱不能清楚地表達其用途時，應添加註解以說明它們的功能和用途。
3. 特定的解決方案或選擇：當選擇特定的實作方式而不是其他可能的解決方案時，註解可以幫助後續的開發者快速理解。
4. 已知的問題或缺陷：如果程式碼中存在已知的問題或缺陷，應加註解來警告其他開發者並提供可能的解決方案或替代方法。
5. 業務邏輯：當有特定的業務規則或需求影響程式碼的實作，應在程式碼中加上註解。
6. 外部依賴：若程式碼依賴於特定的外部資源或API，應在註解中說明這些依賴的存在和使用方式。
7. To-Do 和 FixMe：使用 To-Do 和 FixMe 註解來標記未完成的任務或需要修正的地方。

註解撰寫規則方法與範例：

註解撰寫原則：

1. 充分說明意圖：註解應該清楚地說明程式碼的意圖，而不是重複程式碼所表達的內容。
2. 簡短明瞭：註解應該簡短且易於理解，避免過多的技術術語。

範例 1. function 底下請寫註解、業務功能說明、return 說明

function calculateDiscountedPrice(price, discount) {
/* 計算商品折扣價格（title）
   1. 如果折扣大於 50%，則視為不合法，將折扣設為 50%，避免極端促銷導致的虧損。（說明 1：業務功能需求。）
   2. return 計算後的折扣價格（說明2：說明結果。）
*/
    if (price < 0) {
        throw new Error("價格不能為負數");
    }
    
    if (discount > 0.5) {
        discount = 0.5;
    }

    return price * (1 - discount);
}

let price = 100;
let discount = 0.6;
console.log(calculateDiscountedPrice(price, discount));

範例 2. 接外部 API 、TO-DO 提醒

async function getWeatherData(city) {
/* 向外部天氣 API 請求天氣資料（title）
   1. TO-DO 錯誤檢查強化：應更具體地區分錯誤的類型，例如是否是網路連接問題、API 回應格式錯誤、或是伺服器端的問題。
*/
    const apiKey = "YOUR_API_KEY";
    const apiUrl = `https://api.weather.com/v3/weather/forecast?city=${city}&key=${apiKey}`;

    try {
        
        const response = await fetch(apiUrl);

        // 檢查API回應是否正常
        if (!response.ok) {
            throw new Error("無法獲取天氣數據");
        }

        // 返回JSON格式的天氣數據
        return await response.json();
    } catch (error) {
        // TODO: 錯誤處理待改善，應加強錯誤檢查邏輯
        console.error("獲取天氣數據時發生錯誤:", error);
    }
}

getWeatherData("Taipei").then(data => console.log(data));