btcd项目代码格式化规范详解

btcd项目代码格式化规范详解

btcd An alternative full node bitcoin implementation written in Go (golang) 项目地址: https://gitcode.com/gh_mirrors/bt/btcd

为什么代码格式化如此重要？

在软件开发领域，代码被阅读的次数远超过被修改的次数。对于像btcd这样的开源项目而言，良好的代码格式能够显著提升代码的可读性和维护性。Go语言本身通过go fmt工具已经提供了一套基础的格式化标准，但开发者之间仍然可能存在风格差异。

btcd项目通过制定额外的格式化规则，旨在统一代码风格，使项目代码保持一致的视觉呈现，从而降低开发者的认知负担，提高协作效率。

代码间距规范

逻辑分块原则

代码应当按逻辑功能划分为多个段落，每个段落之间使用空行分隔。这种风格使得代码更易于快速浏览和理解。

不良实践示例

witness := make([][]byte, 4)
witness[0] = nil
if bytes.Compare(pubA, pubB) == -1 {
    witness[1] = sigB
    witness[2] = sigA
} else {
    witness[1] = sigA
    witness[2] = sigB
}
witness[3] = witnessScript
return witness

良好实践示例

witness := make([][]byte, 4)

// 当花费p2wsh多重签名脚本时，我们添加一个nil栈元素
witness[0] = nil

// 确保签名按照正确顺序出现在栈上
if bytes.Compare(pubA, pubB) == -1 {
    witness[1] = sigB
    witness[2] = sigA
} else {
    witness[1] = sigA
    witness[2] = sigB
}

// 最后添加见证脚本作为最后一个元素
witness[3] = witnessScript

return witness

控制结构间距

在switch-case和select语句中，每个case块之间应当有空行分隔。

良好实践示例

switch {
    // 情况A的描述
    case a:
        <代码块>

    case b:
        <代码块>

    default:
        <代码块>
}

代码风格约束

80字符行宽限制

所有代码行应当尽量控制在80字符宽度内。编辑器应当将制表符(tab)设置为8个空格宽度。

字符串换行示例

myKey := "0214cd678a565041d00e6cf8d62ef8add33b4af4786fb2beb87b366a2e1" +
    "51fcee7"

函数调用换行规范

当函数调用过长需要换行时，右括号应当单独成行，所有参数应当在新行开始。

良好实践示例

value, err := bar(
    a, a, b, c,
)

日志和错误消息例外

对于日志和错误消息，应当尽量保持紧凑格式，同时仍遵守80字符限制。

良好实践示例

return fmt.Errorf("this is a long error message with a couple (%d) place "+
    "holders", len(things))

log.Debugf("Something happened here that we need to log: %v",
    longVariableNameHere)

结构化日志规范

1. 静态消息原则：应当使用键值对而非格式化字符串构造日志消息
2. 键值对格式：建议使用slog.Attr辅助函数确保键值对正确性
3. 换行例外：结构化日志允许突破80字符限制以提高可读性

良好实践示例

log.InfoS(ctx, "Channel open performed",
    slog.Int("user_id", userID),
    btclog.Fmt("amount", "%.8f", 0.00154))

函数定义换行规范

函数定义过长需要换行时，应当保持缩进一致，且行尾不应出现未闭合的括号。

良好实践示例

func longFunctionName(
    a, b, c) (d, error) {

    var a int
}

编辑器配置建议

为方便遵守上述规范，建议配置编辑器：

1. 设置制表符宽度为8个空格
2. 在80字符处显示垂直参考线

支持EditorConfig的编辑器会自动应用项目中的格式设置。对于Vim用户，可添加set colorcolumn=80配置。

通过遵循这些代码格式化规范，btcd项目能够保持代码风格的一致性，提高代码可读性和维护性，为开发者创造更好的协作环境。

btcd An alternative full node bitcoin implementation written in Go (golang) 项目地址: https://gitcode.com/gh_mirrors/bt/btcd