如何真正寫好代碼註釋—現代JavaScript教程

NO IMAGE

如何真正寫好代碼註釋—現代JavaScript教程

註釋

正如我們在 代碼結構 一文所瞭解到的那樣,註釋可以是以 // 開始的單行註釋,也可以是 /* ... */ 結構的多行註釋。

我們通常通過註釋來描述代碼怎樣工作和為什麼這樣工作。

乍一看,寫註釋可能很簡單,但初學者在編程的時候,經常錯誤地使用註釋。

糟糕的註釋

新手傾向於使用註釋來解釋“代碼中發生了什麼”。就像這樣:

// 這裡的代碼會先做這件事(……)然後做那件事(……)
// ……誰知道還有什麼……
very;
complex;
code;

但在好的代碼中,這種“解釋性”註釋的數量應該是最少的。嚴格地說,就算沒有它們,代碼也應該很容易理解。

關於這一點有一個很棒的原則:“如果代碼不夠清晰以至於需要一個註釋,那麼或許它應該被重寫。”

配方:分解函數

有時候,用一個函數來代替一個代碼片段是更好的,就像這樣:

function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
// 檢測 i 是否是一個質數(素數)
for (let j = 2; j < i; j++) {
if (i % j == 0) continue nextPrime;
}
alert(i);
}
}

更好的變體,使用一個分解出來的函數 isPrime

function showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) continue;
alert(i);  
}
}
function isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}

現在我們可以很容易地理解代碼了。函數自己就變成了一個註釋。這種代碼被稱為 自描述型 代碼。

配方:創建函數

如果我們有一個像下面這樣很長的代碼塊:

// 在這裡我們添加威士忌(譯註:國外的一種酒)
for(let i = 0; i < 10; i++) {
let drop = getWhiskey();
smell(drop);
add(drop, glass);
}
// 在這裡我們添加果汁
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
examine(tomato);
let juice = press(tomato);
add(juice, glass);
}
// ...

我們像下面這樣,將上面的代碼重構為函數,可能會是一個更好的變體:

addWhiskey(glass);
addJuice(glass);
function addWhiskey(container) {
for(let i = 0; i < 10; i++) {
let drop = getWhiskey();
//...
}
}
function addJuice(container) {
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
//...
}
}

同樣,函數本身就可以告訴我們發生了什麼。沒有什麼地方需要註釋。並且分割之後代碼的結構也更好了。每一個函數做什麼、需要什麼和返回什麼都非常地清晰。

實際上,我們不能完全避免“解釋型”註釋。例如在一些複雜的算法中,會有一些出於優化的目的而做的一些巧妙的“調整”。但是通常情況下,我們應該儘可能地保持代碼的簡單和“自我描述”性。

好的註釋

所以,解釋性註釋通常來說都是不好的。那麼哪一種註釋才是好的呢?

描述架構
: 對組件進行高層次的整體概括,它們如何相互作用、各種情況下的控制流程是什麼樣的……簡而言之 —— 代碼的鳥瞰圖。有一個專門用於構建代碼的高層次架構圖,以對代碼進行解釋的特殊編程語言 UML。絕對值得學習。

記錄函數的參數和用法:有一個專門用於記錄函數的語法 JSDoc:用法、參數和返回值。

例如:

/**
* 返回 x 的 n 次冪的值。
*
* @param {number} x 要改變的值。
* @param {number} n 冪數,必須是一個自然數。
* @return {number} x 的 n 次冪的值。
*/
function pow(x, n) {
...
}

這種註釋可以幫助我們理解函數的目的,並且不需要研究其內部的實現代碼,就可以直接正確地使用它。

順便說一句,很多諸如 WebStorm 這樣的編輯器,都可以很好地理解和使用這些註釋,來提供自動補全和一些自動化代碼檢查工作。

當然,也有一些像 JSDoc 3 這樣的工具,可以通過註釋直接生成 HTML 文檔。你可以在 usejsdoc.org/ 閱讀更多關於 JSDoc 的信息。

為什麼任務以這種方式解決:寫了什麼代碼很重要。但是為什麼 那樣寫可能對於理解正在發生什麼更重要。為什麼任務是通過這種方式解決的?代碼並沒有給出答案。

如果有很多種方法都可以解決這個問題,為什麼偏偏是這一種?尤其當它不是最顯而易見的那一種的時候。

沒有這樣的註釋的話,就可能會發生下面的情況:

  1. 你(或者你的同事)打開了前一段時間寫的代碼,看到它不是最理想的實現方式。
  2. 你會想:“我當時是有多蠢啊,現在我真是太聰明瞭”,然後用“更顯而易見且正確的”方式重寫了一遍。
  3. ……重寫的這股衝動勁是好的。但是在重寫的過程中你發現“更顯而易見”的解決方案實際上是有缺陷的。你甚至依稀地想起了為什麼會這樣,因為你很久之前就已經嘗試過這樣做了。於是你又還原了那個正確的實現,但是時間已經浪費了。

解決方案的註釋非常的重要。它們可以幫助你以正確的方式繼續開發。

代碼有哪些巧妙的特性?它們被用在了什麼地方:如果代碼存在任何巧妙和不顯而易見的方法,那絕對需要註釋。

總結

一個好的開發者的標誌之一就是他的註釋:它們的存在甚至它們的缺席(譯註:在該註釋的地方註釋,在不需要註釋的地方則不註釋,甚至寫得好的自描述函數本身就是一種註釋)。

好的註釋可以使我們更好地維護代碼,一段時間之後依然可以更高效地回到代碼高效開發。

註釋這些內容:

  • 整體架構,高層次的觀點。
  • 函數的用法。
  • 重要的解決方案,特別是在不是很明顯時。

避免註釋:

  • 描述“代碼如何工作”和“代碼做了什麼”。
  • 避免在代碼已經足夠簡單或代碼有很好的自描述性而不需要註釋的情況下,還寫些沒必要的註釋。

註釋也被用於一些如 JSDoc3 等文檔自動生成工具:他們讀取註釋然後生成 HTML 文檔(或者其他格式的文檔)。

本文首發於微信公眾號「技術漫談」,歡迎微信搜索關注,訂閱更多精彩內容。


現代 JavaScript 教程:開源的現代 JavaScript 從入門到進階的優質教程。React 官方文檔推薦,與 MDN 並列的 JavaScript 學習教程

在線免費閱讀:zh.javascript.info


掃描下方二維碼,關注微信公眾號「技術漫談」,訂閱更多精彩內容。

如何真正寫好代碼註釋—現代JavaScript教程

相關文章

SpringSecurityOAuth2開發者指南譯

基於Webpack4的Vue移動端開發環境搭建篇

CSS3Transition過渡動畫用法介紹

Java線程池的四種用法與使用場景