用 JavaScript 註釋代碼 - 類型和最佳實踐

簡介

編寫代碼的主要目的是讓計算機可以將其解釋為命令。但是，同樣重要的是，我們編寫的代碼也很容易被其他開發人員解釋。

您是否曾經回到一個項目並且難以理解內部邏輯？嗯，這可能是因為該項目尚未評論 正確。

評論 是用 JavaScript 引擎忽略的代碼中編寫的註釋，這意味著它們不會以任何方式影響輸出。他們的唯一目的是描述代碼如何以及為什麼對其他開發人員和您自己有效。

在本文中，我們將了解如何評論 JavaScript 代碼 ，以及存在哪些類型的評論，以及一些最佳做法。

單行註釋

單行註釋一般用於註釋行的一部分 或整行代碼 . JavaScript 中的單行註釋以 // 開頭 .解釋器將忽略此控制序列右側的所有內容，直到行尾。

讓我們看一個實際的單行註釋示例：

// Print "Hello World" in the console
console.log("Hello World");

在這裡，我們使用單行註釋來描述下一行代碼在做什麼。
如果單行註釋出現在一行代碼的末尾，則稱為內聯註釋 .

這些一般用於添加快速註釋：

let c = a + b; // Assign sum of a, b to c

多行註釋和 JavaScript DocStrings

如果我們想添加跨多行的註釋，我們可以選擇多行註釋或塊級註釋 .

多行註釋以 /* 開頭 並以 */ 結尾 ：

/* The following program contains source code for a game called Tic-tac-toe.
It is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3×3 grid. 
The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row is the winner
*/

在這裡，多行註釋用於描述井字遊戲。一般多行註釋用於介紹和解釋一段代碼，單行/一句話是不夠的。

也經常可以看到另一種類型的多行註釋：

/**
* The following program contains source code for a game called Tic-tac-toe.
* It is a paper-and-pencil game for two players, X and O, who take turns marking the
* spaces in a 3×3 grid. 
* The player who succeeds in placing three of their marks in a horizontal, vertical, or 
* diagonal row is the winner
*/

通常，這些註釋可以包含有關正在執行的代碼的信息，例如函數的參數，甚至代碼的作者：

/**
* Function that greets a user
* @author   John
* @param    {String} name    Name of the user
* @return   {String}         Greeting message
*/
function greetUser(name) {
    return `Greetings, ${name}!`;
}

這些註釋被稱為 DocStrings ，因為它們本質上是構成代碼文檔的字符串（註釋）。

這些類型的評論對您團隊中的其他開發人員非常有用，因為您可以闡明預期的輸入是什麼，輸出是什麼，以及在需要時聯繫誰。

另一個好處是您可以根據這些 DocStrings 生成文檔。

使用註釋進行調試

除了做筆記，註釋還可以用於快速阻止代碼執行以進行調試。這是可能的，因為 JavaScript 引擎不解釋註釋代碼。這稱為註釋掉代碼 .

如果有錯誤的行，這會導致問題，我們可以簡單地“註釋掉” 禁用它，而不刪除該行。這可以與實際的調試器配對，以幫助您評估正在發生的事情。

考慮以下代碼：

console.log("Working code");
console.log("Erroneous code);

如果我們想刪除第二條語句，但又不想永遠刪除它，我們可以簡單地將其註釋掉：

console.log("Working code");
//console.log("Erroneous code);

專業提示 ：在大多數代碼編輯器中，我們可以使用鍵盤快捷鍵Ctrl + / 適用於 Windows 和 Cmd + / 讓 Mac 註釋掉一行代碼。

此外，如果您不確定是否要刪除它們，您還可以將整個部分註釋掉：

免費電子書：Git Essentials

查看我們的 Git 學習實踐指南，其中包含最佳實踐、行業認可的標準以及隨附的備忘單。停止谷歌搜索 Git 命令並真正學習 它！

/*console.log("Entering for loop");
for (let i = 0; i < 100; i++) {
    console.log(i);
}*/

良好的評論實踐

首先，註釋不是寫不可讀代碼的藉口，然後用五段註釋來解釋它。我們首先必須專注於編寫乾淨、不言自明的代碼，以後可以通過建設性的評論對其進行改進。

使用註釋來解釋為什麼 你做了某事，而不是如何 你做到了。如果你發現自己在解釋你是如何做某事的，那麼是時候退後一步，將你的代碼重構為不言自明的東西。

另一條建議是不要寫明顯且本質上是多餘的評論。例如，下面的註釋是完全沒有必要的：

// Prints out the result
console.log(result)

有一些有用的工具，例如 JSDOC 3，可以僅根據代碼中的註釋生成文檔，這些註釋被格式化為上述 DocStrings。

結論

在本文中，我們討論了什麼是註釋以及如何在 JavaScript 中創建它們。我們查看了不同類型的評論 - 單行 和多行 評論，以及提到的 JavaScript Docstrings。

我們還看到瞭如何使用一種叫做“註釋掉”的技術來調試我們的代碼，最後總結了一些很好的註釋實踐。