Go 語言中常見問題 - 缺少代碼文檔

文檔（代碼註釋）是編碼的一個重要方面，它可以降低客戶端使用 API 的複雜度，也有助於項目維護。在 Go 語言中，我們應該遵循一些規則使得我們的代碼更地道。下面一起來看看這些規則。

每個可導出的元素必須添加文檔說明，無論是結構體、接口、函數還是其他元素。如果它被導出，則必須有文檔說明。通用的文檔說明是添加註釋，註釋前以元素名稱開始，像下面這樣。

// Customer is a customer representation.
type Customer struct{}
 
// ID returns the customer identifier.
func (c Customer) ID() string { return "" }

按照慣例，每條註釋都應該是一個以 . 標點符號結尾的完整句子。此外，當對一個函數（或方法）註釋說明時，應該強調函數打算做什麼，而不是它是如何實現的。函數實現的功能、目的纔是屬於函數和註釋的核心。理想情況下，文檔註釋應該提供足夠的信息，使得使用者不必查看源碼即可瞭解如何使用導出的元素。

棄用元素

可以使用 // Deprecated: 註釋來棄用導出的元素。像下面這樣，當開發人員再調用 ComputePath 函數時，會收到警告信息 (大多數 IDE 不推薦使用棄用的元素)。

// ComputePath returns the fastest path between two points.
// Deprecated: This function uses a deprecated way to compute
// the fastest path. Use ComputeFastestPath instead.
func ComputePath() {}

當對變量或常量進行註釋說明時，我們可能想傳遞兩方面內容：它的目的和內容. 變量或常量的目的應該作爲代碼文檔存在，以便對外部使用者有所幫助。但是變量或常量的內容不一定需要被使用者看到。例如下面的代碼。DefaultPermission 表示默認權限，代碼文檔註釋說明了該變量的目的，而常量旁邊的註釋描述了它的實際內容（讀寫權限）。

// DefaultPermission is the default permission used by the store engine.
const DefaultPermission = 0o644 // Need read and write accesses.

爲了能夠讓程序的使用者和維護人員瞭解包的範圍，還應該給包添加文檔說明。按照慣例，註釋以 //Package 開頭，後面跟 Package 名稱：

// Package math provides basic constants and mathematical functions.
//
// This package does not guarantee bit-identical results
// across architectures.
package math

包的第一行註釋應該簡潔，因爲它將出現在包的文檔中。如下圖所示，每個包名後的簡潔說明來自包中文檔的第一行說明。

可以在任何 Go 文件中編寫包文檔，沒有規則限制。通常，我們應該將包文檔放在與包同名的相關 Go 文件中，或者放在特定文件中，如 doc.go. 關於包文檔，最後要說的一點是，與聲明不相鄰的註釋會被省略。例如，下面的版權註釋在生成的 Go 文檔中不可見。

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package math provides basic constants and mathematical functions.
//
// This package does not guarantee bit-identical results
// across architectures.
package math

總之，我們應該記住，每個導出的元素都需要有文檔說明。代碼註釋文檔說明不應該成爲一種約束，相反，我們應該充分利用它，確保通過它能夠幫助程序使用者和維護人員理解代碼用途。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/x1bJChX6T4mNPZVikUd2KA