如何在 JavaScript 中寫註釋
這篇文章最初是為 DigitalOcean 寫的。
簡介
在編程中,我們首先考慮的通常是機器——計算機如何讀取和解釋我們編寫的代碼。然而,考慮將閱讀和使用代碼的人也同樣重要。無論您是與團隊合作還是獨自工作,您都需要學習為人類讀者正確地註釋和構建您的代碼。
註釋是程序源代碼中被解釋器忽略的註釋,因此對代碼的實際輸出沒有影響。註釋對於解釋代碼正在或應該做什麼的意圖非常有幫助。
作為一名開發人員,深入研究由其他人編寫的未正確註釋的代碼可能會令人沮喪,而且當您不再沉浸在程序的上下文中時,很容易忘記自己的代碼的含義。儘早評論您的代碼將在您的整個職業生涯中加強良好的編程習慣,以避免以後出現這些問題。
評論語法
讓我們快速瀏覽一下兩種不同類型的 JavaScript 註釋語法。
單行 註釋用兩個正斜杠 (//
):
// This is a comment
//
之後的所有字符 JavaScript 將忽略直到行尾的語法。
屏蔽 註釋,有時稱為多行 註釋,用開始標籤(/*
) 和結束標籤 (*/
)。如果您了解 CSS,那麼您已經熟悉塊級註釋。
/* This is
a comment */
上面代碼塊中開始和結束標記之間的所有內容都將被忽略。
單行和多行註釋都寫在它們被指定解釋的代碼之上,如“Hello, World!”中所示。例子:
// Print "Hello, World!" to the console
console.log('Hello, World!')
編寫註釋時,將它們與緊隨其下的代碼同級縮進:
// Initialize a function
function alphabetizeOceans() {
// Define oceans variable as a list of strings
const oceans = ['Pacific', 'Atlantic', 'Indian', 'Antarctic', 'Arctic']
// Print alphabetized array to the console
console.log(oceans.sort())
}
請注意,註釋與程序本身一樣是代碼的一部分。過時的評論可能比沒有評論更有害,因此請記住定期維護和更新評論以及其他所有內容。
內嵌評論
單行註釋稱為內聯註釋 當它們出現在一行代碼的末尾時。
let x = 99 // assign numerical value to x
let y = x + 2 // assign the sum of x + 2 to y
內聯註釋可用於對小的、特定的內容片段進行快速註釋。由於註釋應該只與它所寫的確切行相關,因此它是最明顯的註釋類型。
請記住,沒有辦法在一行中結束單行註釋,因此請確保不要在 //
之後放置任何代碼 語法,如下例所示。
for (let i = 0; i === 10; i++) // for loop that runs ten times {
// Running this code results in a syntax error
}
雖然內聯註釋很有用,但應謹慎使用——被大量內聯註釋覆蓋的代碼很快就會變得雜亂無章,因此難以閱讀。
塊評論
塊級註釋或多行註釋是用於介紹和解釋一段代碼的長格式註釋。這些類型的註釋通常放在文件的頂部,或者放在特別複雜的代碼塊之前。
/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */
function greetUser() {
const name = prompt('What is your name?')
console.log('Hello ,' + name + '! How are you?')
}
greetUser()
您有時可能還會看到塊註釋語法的略微修改版本,它以 /**
開頭 並且在整個評論塊的左側都包含星號。
/**
* Initialize constant with an array of strings.
* Loop through each item in the array and print
* it to the console.
*/
const seaCreatures = ['Shark', 'Fish', 'Octopus']
for (const seaCreature of seaCreatures) {
console.log(seaCreature)
}
有時這種類型的註釋還會包含有關編程文件的詳細信息,包括腳本的名稱、版本和作者。
如果您是 JavaScript 的初學者,您可以編寫盡可能多的內容來學習和理解您編寫的代碼。隨著您作為 JavaScript 開發人員的進步,您將尋求回答意圖或為什麼 在代碼背後,而不是如何 或什麼 .
註釋掉測試代碼
註釋還可用於快速輕鬆地阻止執行代碼以進行測試和調試。這被稱為“註釋掉代碼”。
如果您編寫的某些代碼存在錯誤,註釋掉部分將阻止它們運行,並且有助於查明問題的根源。您也可以使用它在代碼之間切換以測試不同的結果。
// Function to add two numbers
function addTwoNumbers(x, y) {
let sum = x + y
return sum
}
// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
let product = x * y
return product
}
/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */
// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9)
單行註釋和塊註釋都可以用來註釋代碼,具體取決於被切換部分的大小。
在計算程序的邏輯時,註釋掉代碼會很有幫助,因為您可以確定錯誤在哪里或評估最實用的代碼行。
結論
JavaScript 代碼由計算機解釋,但總是會被其他程序員閱讀,包括你未來的自己。花時間在復雜的代碼部分留下適當的註釋將在未來獲得回報,讓您和協作者更容易理解您編寫的代碼的意圖。