註解 在

關於 註解

註解讓你能在程式碼中留下筆記，而不影響程式執行。 單行註解從一行的任何位置以 // 開始。 編譯器會忽略從 // 到該行結尾的所有內容。 當註解出現在同一行的程式碼之後時，通常稱為行內註解。 多行註解從一行的任何位置以 /* 開始，並以 */ 結束。 編譯器會忽略中間的所有內容，這些內容可以橫跨一行或多行。

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

註解會依出現的位置而有不同的用途。

程式碼註解

程式碼註解說明的是為什麼要這麼做，而不是做了什麼。 當某個決定背後的理由無法從程式碼中一眼看出時，就用它們：

results = results[1:] // skipping the header row

大多數情況下，寫得清楚的程式碼本身就能說明一切，不需要註解。 偶爾，程式碼必須做一些複雜或出乎意料的事；這類程式碼就應該加上註解。

文件註解

文件註解用來為套件、變數或函式撰寫說明文件。 這份說明文件的對象是其他想了解如何_使用_你的程式碼的開發者。 它應該從高階的角度說明這段程式碼的功能，以及該如何使用。 它不應包含程式碼本身運作方式的細節。 文件註解會緊接在宣告之前，註解與宣告之間不留空行。 godoc會解析這些註解來產生套件說明文件，就像 pkg.go.dev 上看到的那樣。 文件註解應該是一個完整的句子，以識別字的名稱開頭，並以句號結尾。

匯出識別字（以大寫字母開頭的那些）上的文件註解會出現在產生的說明文件中。 未匯出識別字（不以大寫字母開頭的那些）上的文件註解不會出現，但仍能在程式碼中提供有用的背景資訊。

為套件撰寫的文件註解會以套件名稱開頭，並描述這個套件的功能：

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

為函式撰寫的文件註解會以函式名稱開頭，並描述這個函式的功能，包括它的引數與回傳值：

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

為變數撰寫的文件註解會以變數名稱開頭，並描述這個變數代表的意義：

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

完整的文件註解規格請參閱 Go 說明文件指南。