Go Docstring编写指南

本文档介绍如何为Go代码编写结构化的文档注释（docstring），包括变量、函数、结构体等元素的注释规范和最佳实践。

目录

• 基础规范
• 包注释
• 函数注释
• 类型注释
• 变量与常量注释
• 注释语法
• 最佳实践
• 常见错误

基础规范

什么是Docstring

Docstring是紧接在顶层声明之前且没有换行符分隔的注释。Go的文档工具（如go doc和pkg.go.dev）会自动提取这些注释生成文档。

核心原则

每个导出的（大写字母开头）名称都应该有docstring

基本规则

// 正确的位置：注释紧邻声明，中间无空行
// SomeFunction returns the sum of two numbers.
func SomeFunction(a, b int) int {
    return a + b
}

// 错误：注释与声明之间有空行
// SomeOtherFunction returns the difference of two numbers.

func SomeOtherFunction(a, b int) int {
    return a - b
}

单行vs多行注释

// 单行注释适用于简单说明
// MaxConnections is the maximum number of concurrent connections.
const MaxConnections = 100

// 多行注释适用于复杂说明
// ProcessRequest handles an incoming request and returns the response.
// It validates the input, applies any necessary transformations, and
// executes the business logic before returning the result.
func ProcessRequest(req Request) Response {
    // ...
    return response
}

包注释

简单包注释

对于简单包，注释可以很简短：

// Package stringutil contains utility functions for string manipulation.
package stringutil

详细包注释

复杂包应包含更多上下文信息：

// Package ratelimit implements distributed rate limiting with lease-based coordination.
//
// This package uses a two-phase commit protocol to ensure consistency across
// multiple nodes in a cluster. Rate limits are enforced through sliding time
// windows with configurable burst allowances.
//
// The package provides the following key features:
//   - Sliding window rate limiting
//   - Cluster-wide coordination
//   - Configurable burst allowances
//   - Automatic failover
//
// # Key Types
//
// The main entry point is [RateLimiter], which provides the [RateLimiter.Allow]
// method for checking rate limits. Configuration is handled through [Config].
package ratelimit

提示

包注释的第一句话应该以"Package <name>"开头，这是一条惯例

doc.go文件

对于大型或多文件包，建议使用doc.go文件集中存放包注释：

// Package cache provides a thread-safe in-memory cache with TTL support.
//
// This implementation uses a read-write mutex pattern to allow concurrent
// reads while ensuring exclusive writes. Each cache entry has an optional
// time-to-live value that controls when entries expire.
//
// # Performance Characteristics
//
// Read operations are O(1) and do not block other readers.
// Write operations have O(1) average time complexity but may block readers.
package cache

文件内容：

// Package cache provides a thread-safe in-memory cache with TTL support.
//
// The package provides thread-safe caching with automatic expiration.
// See the main package documentation for full details.
package cache

函数注释

基本格式

// Add returns the sum of two integers.
// It panics if the result overflows int.
func Add(a, b int) int {
    if a > 0 && b > 0 && a > math.MaxInt-b {
        panic("integer overflow")
    }
    return a + b
}

带参数的函数

函数的docstring应解释返回值，对于有命名参数的函数，可以直接引用参数名：

// Split divides the string s around the first instance of sep,
// returning the text before and after sep respectively.
// If sep is not found, Split returns [s, ""].
// The compare function defines how the separator is matched.
// By default, bytes.Equal is used.
func Split(s, sep string, cmp func([]byte, []byte) bool) (string, string) {
    // implementation
}

方法注释

// SetTimeout sets the maximum duration for this operation.
// It returns an error if the timeout value is negative.
func (c *Client) SetTimeout(timeout time.Duration) error {
    if timeout < 0 {
        return errors.New("timeout cannot be negative")
    }
    c.timeout = timeout
    return nil
}

返回多值的函数

// Lookup searches for the key in the cache and returns its value.
// It returns (value, true) if found, or (zero value, false) if not found.
// The returned value is a copy and safe for modification.
func (c *Cache) Lookup(key string) (Value, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    v, ok := c.items[key]
    return v, ok
}

示例

// New creates a new Logger with the specified configuration.
// The level parameter controls which log levels are enabled.
// Debug and Info levels are always enabled in development.
//
// Example:
//
//	cfg := Config{Level: Debug, Output: os.Stdout}
//	logger := New(cfg)
//	logger.Info("application started")
func New(cfg Config) *Logger {
    // implementation
}

类型注释

结构体注释

// Config holds the configuration parameters for the service.
// All fields must be set before calling [New] to create a valid instance.
type Config struct {
    // Address is the host:port string for the server to listen on.
    Address string

    // MaxConnections limits the number of concurrent connections.
    MaxConnections int

    // Timeout sets the request timeout duration.
    Timeout time.Duration

    // TLSConfig optionally specifies TLS settings.
    TLSConfig *tls.Config
}

接口注释

// Logger defines the interface for logging operations.
// Implementations should be safe for concurrent use.
type Logger interface {
    // Debug logs a debug message.
    Debug(msg string, args ...any)

    // Info logs an info message.
    Info(msg string, args ...any)

    // Error logs an error message.
    Error(msg string, args ...any)

    // With returns a logger with additional context.
    With(args ...any) Logger
}

字段注释

结构体字段注释应该清晰说明其用途：

type HTTPClient struct {
    // Transport specifies the mechanism for making HTTP requests.
    // If nil, http.DefaultTransport is used.
    Transport http.RoundTripper

    // CheckRedirect specifies the policy for handling redirects.
    // If CheckRedirect is nil, the client uses its default policy,
    // which stops after 10 consecutive requests.
    CheckRedirect func(req *http.Request, via []*http.Request) error

    // Jar specifies the cookie jar for managing cookies.
    // If Jar is nil, cookies are not sent in requests and are
    // ignored in responses.
    Jar http.CookieJar

    // Timeout specifies the time limit for requests.
    // A timeout of zero means no timeout.
    Timeout time.Duration
}

变量与常量注释

导出变量

// MaxInt64 is the maximum value for an int64.
const MaxInt64 = 1<<63 - 1

// PageSize is the default page size for pagination.
var PageSize = 20

// ErrNotFound is returned when the requested resource does not exist.
var ErrNotFound = errors.New("resource not found")

多个相关常量

// Log levels for controlling logging output.
const (
    // LevelDebug is used for detailed debugging information.
    LevelDebug Level = iota

    // LevelInfo is used for general operational information.
    LevelInfo

    // LevelWarn is used for warning conditions.
    LevelWarn

    // LevelError is used for error conditions.
    LevelError
)

变量组

// Default configuration values.
var (
    // DefaultAddress is the address the server listens on by default.
    DefaultAddress = "localhost:8080"

    // DefaultMaxConnections is the maximum number of concurrent connections.
    DefaultMaxConnections = 100

    // DefaultTimeout is the default request timeout.
    DefaultTimeout = 30 * time.Second
)

注释语法

段落和换行

Go文档注释使用完整句子。可以使用语义换行（一行一句）便于版本控制时查看差异：

// Process handles the incoming data with the following steps:
//
// It first validates the input to ensure all required fields are present
// and have valid values.
// Then it transforms the data into the internal representation.
// Finally it applies the business rules and returns the result.
//
// If any step fails, the function returns an error and does not
// proceed to subsequent steps.
func Process(data []byte) (Result, error) {
    // ...
}

文档链接

使用方括号创建指向其他符号的链接：

// Package path implements utility routines for manipulating slash-separated
// paths.
//
// To manipulate operating system paths, use the [path/filepath] package.
package path

// Find searches for the target in the sorted slice.
// If found, it returns (index, true); otherwise it returns (insertion point, false).
// For details, see [sort.Search].
func Find(slice []int, target int) (int, bool) {
    // ...
}

代码块

// Execute runs the command with the following behavior:
//
//   - Stdout and stderr are captured and returned as combined output
//   - The command runs with the current environment variables
//   - On Unix systems, the command is executed via /bin/sh -c
//
// Example:
//
//	output, err := Execute("echo", "hello", "world")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	fmt.Println(string(output)) // prints: hello world\n
func Execute(name string, args ...string) ([]byte, error) {
    // ...
}

列表

// Feature supports the following operations:
//
//   - Read: retrieve the current value
//   - Write: update the value
//   - Delete: remove the feature flag
//   - List: enumerate all feature flags
type Feature interface {
    // ...
}

最佳实践

1. 使用主动语态

// 好的：使用主动语态
// Validate checks if the input is valid.

// 不好的：使用被动语态
// Is validated whether the input is checked.

2. 以功能名称开头

// Split divides the string at the first occurrence of sep.

// SendMessage sends a message to the specified recipient.

3. 解释原因而非实现

// 好的：解释原因
// Use buffered channel to prevent deadlock when
// the receiver is slow to start.

// 不好的：重复实现
// Acquire the lock, then access the map.

4. 保持简洁

// 好的：简洁明了
// ErrNotFound indicates the requested resource was not found.
var ErrNotFound = errors.New("not found")

// 过度的注释
// ErrNotFound is a global error variable that is returned
// as the error value when the requested resource cannot be
// found in the system. This error is used to indicate that
// the lookup operation failed because the target resource
// does not exist in the current context.
var ErrNotFound = errors.New("not found")

5. 记录错误和警告

// Encode converts value to its JSON representation.
// It returns an error if:
//   - the value cannot be marshaled (e.g., contains channels)
//   - the output buffer is too small
//   - an invalid UTF-8 sequence is encountered
func Encode(value any, w io.Writer) error {
    // ...
}

6. 说明并发安全性

// SafeMap is a concurrent-safe map implementation.
// It is safe for concurrent access from multiple goroutines
// without additional synchronization.
type SafeMap struct {
    // ...
}

// Process is not safe for concurrent use.
// Callers must ensure no other goroutines are accessing
// the instance during calls to Process.
func (p *Processor) Process(data []byte) error {
    // ...
}

7. 版本和变更记录

// SetVersion sets the semantic version of this component.
// As of v2.0, this method is a no-op and returns nil.
// The version is now set during construction via [NewWithVersion].
func (c *Component) SetVersion(v string) error {
    // deprecated: v2.0
    return nil
}

常见错误

1. 注释位置错误

// Wrong: blank line between comment and declaration
// This is the config

type Config struct {
    Field string
}

// Correct: no blank line
// This is the config
type Config struct {
    Field string
}

2. 过度注释

// Bad: obvious comments that don't add value
// Increment i by 1
i++

// Bad: redundant comments that restate the code
// The following line creates a new user
user := NewUser()

3. 缺少关键信息

// Bad: incomplete documentation
// Process processes the data.
func Process(data []byte) error {
    // ...
}

// Good: complete documentation
// Process validates and processes the data.
// It returns ErrInvalidInput if data is empty or malformed.
// Process is safe for concurrent use.
func Process(data []byte) error {
    // ...
}

4. 未更新注释

// Bad: outdated comment
// This function always returns a positive number.
func Calculate(x int) int {
    if x < 0 {
        return -x // now returns negative for negative input
    }
    return x
}

5. 参数和返回值未说明

// Bad: unclear parameters and return values
// DoSomething does something with the stuff.
// It returns whatever it does.
func DoSomething(stuff []byte, count int) ([]byte, error) {
    // ...
}

// Good: clear parameters and return values
// DoSomething processes stuff count times and returns the result.
// It returns (processed stuff, nil) on success or (nil, error) on failure.
func DoSomething(stuff []byte, count int) ([]byte, error) {
    // ...
}

工具和命令

查看文档

# 查看包的文档
go doc package

# 查看特定符号的文档
go doc package Symbol

# 启动本地文档服务器
godoc -http=:6060

静态分析

# 检查缺少文档的导出符号
golint ./...

# 运行所有检查
go vet ./...

生成文档网站

# 安装 godoc
go install golang.org/x/tools/cmd/godoc@latest

# 启动文档服务器
godoc -http=:6060

总结

编写高质量的Go文档注释需要遵循以下原则：

• 一致性：始终为导出的符号添加文档注释
• 清晰性：使用简洁、准确的语言描述功能和用途
• 完整性：说明参数、返回值、错误和副作用
• 实用性：解释原因和上下文，而不仅仅是重复代码
• 可维护性：更新注释以反映代码变更

良好的文档注释不仅帮助其他开发者理解代码，还能在go doc、pkg.go.dev等工具中生成专业的API文档。