多年來圍繞著評論存在著許多爭論。許多人堅持認為“好的程式碼會自我註釋”，而其他人則贊成在程式碼中包含好的註釋，並認為應該需要它們。當我閱讀和聽到這些爭論時，我注意到他們經常關注程式碼的什麼和如何......即。程式碼做什麼，以及如何做到這一點。但「為什麼」的概念很少進入討論…即。 為什麼需要這段程式碼，或是為什麼要這樣寫。儘管雙方都有有效的論據，但很難知道該往哪個方向走。這促使我建立了 3 條規則，我相信這不僅有助於彌合兩者，而且還能鼓勵編寫更好的程式碼。我想與您分享我的 3 條規則，希望它們能像我一樣對您有所幫助。
規則 1：名稱要解釋什麼
程式碼中的變數、參數、介面、函數、類別、方法或其他「事物」的名稱應提供足夠的訊息，以清楚地描述該事物的「什麼」功能或它所具有的「什麼」值。另一個開發人員應該能夠在幾週或幾個月後讀取該事物的名稱，並準確地知道它的功能或它所擁有的內容，而無需詢問、查看額外的程式碼或閱讀額外的文件。如果這樣做，則應更改名稱以使其更清晰。
為了在這裡澄清一點，重要的是要注意名稱不負責描述某些東西的“用途”。名稱僅負責描述該事物的“做什麼”，或該事物所具有的“什麼”價值。
讓我們來看一些我個人遇到的例子來幫助澄清這一點：
const derivatives = [];
只知道這個名字，你就能知道這個陣列裡會保存什麼樣的資料嗎？顯然它包含了從其他東西複製或改編的東西......但是這些資訊足夠嗎？試著退一步思考，如果您在正在編寫的某些程式碼中遇到此問題，您會問自己或其他人甚麼樣的問題。
function name(user) {
// ...
}
這裡我們有一個函數正在執行與用戶名相關的操作...現在，無需閱讀其他程式碼或向某人詢問更多上下文，您能說出這個函數的作用嗎？
當我遇到這個問題時，我必須查看更多程式碼才能弄清楚它做了什麼......在我問“這是否返回名稱？”，“這是否會更新名稱？”或“這是否構造來自其他資料的名字？”
希望您能看到上面的範例不是好名稱，需要更改，因為它們不符合此規則的要求。您將不得不查看更多程式碼或詢問其他人來弄清楚他們做什麼或持有什麼。那什麼是更好的名字呢？顯然，我們可以使用很多不同的名稱，但這裡有幾個例子：
const derivativeUsers = [];
透過這個更新後的名稱，我們現在可以知道該陣列將容納一定數量的從其他陣列複製或改編的用戶。無需閱讀額外的程式碼或詢問其他人。哈札！
function getFullName(user) {
// ...
}
在這裡，我們更改了函數的名稱，以更清楚地說明該函數的什麼功能。透過這個簡單的更新，我們現在知道該函數傳回傳遞給它的使用者的全名。
因此，總結第一條規則，您在程式碼中命名的任何內容都應該清楚地描述該事物的什麼，或什麼值（如果成立）。這可能會讓你的名字變得更冗長一些，但在我個人看來，如果更冗長一點意味著程式碼對你和團隊來說更具可讀性和可維護性，那麼這是值得付出的代價。
規則 2：程式碼應解釋如何
雖然事物的名稱告訴了它“做什麼”，但它內部的程式碼應該描述它“如何”做到這一點。現在，這可能聽起來有點明顯，但它帶來了一些您必須考慮的事情。
為了讓其他人理解程式碼「如何」執行某些操作，它必須具有可讀性和可理解性。如果沒有人能夠理解執行操作的程式碼，那麼它的好處就會少很多。其中一部分來自於組成程式碼的各個部分的命名。但有助於程式碼可讀和理解的其他因素包括簡單性、組織和結構、格式和樣式，僅舉幾例。
這是一個很大的話題，有很多關於它的文章、書籍和課程，所以我不會在這裡討論太多細節。只需要知道，編寫乾淨的程式碼是編寫可讀且可理解的程式碼的一個非常重要的部分，它可以讓團隊的其他成員知道「如何」某件事是如何做到的。
另一個難題是模組化。如果某個東西很小並且只做一件事，那麼理解它是如何做的就容易多了。您可能在您的職業生涯中以某種形式聽說過這個概念。也許您熟悉單一職責原則，即 [SOLID 原則] 中的「S」(https://www.goodreads.com/book/show/25936819-design-principles-and-design-patterns) 。如果您還不熟悉，我強烈建議您研究一下，因為它是軟體開發領域的重要概念。但回到正題。如果一個函數、類別、方法、元件或其他任何東西執行不只一件事，則程式碼的複雜性會急劇增加，並且不僅辨識如何它是如何做到的，而且隨著時間的推移，維護它也會變得更加困難。
因此，為了使您的程式碼符合第二條規則，您或團隊的其他成員必須在幾個月後能夠理解它。他們應該能夠查看某些“事物”的程式碼，並能夠輕鬆辨識它“如何”執行其功能。為了實現這一點，我們必須編寫乾淨、可讀、可理解的程式碼。
規則 3：評論應該解釋為什麼
最後，當需要更多資訊時，當我們需要了解「什麼」和「如何*」之外的內容時，我們需要「為什麼」…這就是評論來拯救世界的地方。當我們編寫程式碼時，有時我們需要傳遞更多訊息，例如「為什麼」做出決定、「為什麼」需要一段程式碼或與之相關的一些其他上下文。這些都是應該評論的事情。
在編輯不是立即顯而易見的特定程式碼區塊時，可能需要考慮一些晦澀的用例。這應該被清楚地註釋，這樣當下一個開發人員下週、下個月甚至明年返回這段程式碼時，他們也會考慮到這些訊息，而不是重新引入一些錯誤，或破壞其他一些部分的功能。
也許由於某些第三方依賴項的工作方式，必須在程式碼的特定區域執行一些不「正常」的操作。與其期望團隊的其他成員遇到同樣的問題並必須自己解決，不如對情況進行評論，以節省他們以後的時間（可能是幾個小時甚至幾天）。
理解「為什麼」某件事以這種方式完成可以提供巨大的洞察力，特別是當有多種路徑可供選擇時，或者如果存在影響決策的間接背景。在我個人看來，評論“為什麼”不僅僅是程式碼中的“很好”，而且至關重要。它對於可維護性、知識共享至關重要，最重要的是對於幫助團隊其他成員成功至關重要。
知道何時應包含“為什麼”有時可能很困難。大多數人，包括我自己，都忘記了我們擁有別人所沒有的知識和理解。我們在生活中假設或期望其他人要么知道這些東西，要么很容易弄清楚……即使我們花了幾個月的時間收集不同的資訊來獲得這些知識。因此，當您編寫下一段程式碼時，請真正退一步思考一下，您認為下一個開發人員將擁有哪些資訊來理解它？然後，在評論中寫下這些內容。
結論
嗯，就是這樣…保存程式碼的 3 個簡單規則。因此，下次當您在流程中編寫下一個重要功能時，請嘗試記住...
命名應該解釋您的程式碼的什麼功能。
程式碼本身應該是可讀且易於理解，以便您和其他人可以輕鬆辨識它如何執行它正在執行的操作。
使用註解提供所有額外訊息，以便每個人都知道為什麼程式碼是這樣編寫的。
希望這3條規則對你的職涯有幫助！下次見，駭客快樂！
原文出處：https://dev.to/wraith/my-3-rules-for-documenting-code-2f54
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
