# 风格原则参考

## 1. 清晰性

代码的目的和原理必须对读者清晰。

- **做什么**：使用描述性名称、有帮助的注释和高效的组织
- **为什么**：添加解释原理的注释，特别是对于微妙的细节
- 从读者的角度审视清晰性，而非作者的角度
- 代码应该易于阅读，而非易于编写

```go
// 好：目的清晰
func (c *Config) WriteTo(w io.Writer) (int64, error)

// 不好：不清晰，重复了接收者
func (c *Config) WriteConfigTo(w io.Writer) (int64, error)
```

## 2. 简洁性

代码应该以最简单的方式实现目标。

简洁的代码：
- 从头到尾容易阅读
- 不假定读者有先验知识
- 没有不必要的抽象层次
- 注释解释"为什么"，而非"做什么"
- 可能与"巧妙"的代码互斥

### 最少机制

当有几种方式表达同一个想法时，优先使用最标准的工具：

1. 核心语言结构（channel、slice、map、loop、struct）
2. 标准库（HTTP 客户端、模板引擎）
3. 第三方库 — 仅在 (1) 和 (2) 不够用时使用

## 3. 精炼性

代码应该有高信噪比。

- 避免重复代码
- 避免多余的语法
- 避免不必要的抽象
- 使用表驱动测试提取公共代码

```go
// 好：常见惯用法，信号量高
if err := doSomething(); err != nil {
    return err
}

// 好：为异常情况增强信号
if err := doSomething(); err == nil { // 如果没有错误
    // ...
}
```

## 4. 可维护性

代码被修改的次数远多于被编写的次数。

可维护的代码：
- 对于未来的程序员来说容易正确修改
- API 能够优雅地扩展
- 使用可预测的名称（相同概念 = 相同名称）
- 最小化依赖
- 具有全面的测试和清晰的诊断信息

```go
// 不好：关键细节被隐藏
if user, err = db.UserByID(userID); err != nil { // = vs :=

// 好：显式且清晰
u, err := db.UserByID(userID)
if err != nil {
    return fmt.Errorf("invalid origin user: %s", err)
}
user = u
```

## 5. 一致性

代码的外观和行为应该与代码库中的类似代码一致。

- 包级别的一致性最重要
- 当出现平局时，优先保持一致性
- 绝不为了局部一致性而覆盖有文档记录的风格原则