标签 Bug 下的文章

一文搞懂如何在Go包中支持Hash-Based Bisect调试

本文永久链接 – https://tonybai.com/2024/mm/dd/how-to-support-hash-based-bisect-in-go-package

bisect是一个英文动词,意为“二分”或“分成两部分”。在数学和计算机科学中,通常指将一个区间或一个集合分成两个相等的部分。

对于程序员来说,最熟悉的bisect应用莫过于下面两个:

  • 算法中的二分查找(binary search)

二分查找是一个经典且高效的查找算法,任何一本介绍数据结构或计算机算法的书都会包含对二分查找的系统说明。所谓二分查找就是通过不断将搜索区间一分为二来找到目标值。一些排序算法也应用了bisect的思想,比如快速排序(QuickSort)等。

  • git bisect

git bisect是一个非常实用的Git命令,它通过二分查找的方式有效缩小可能导致错误的提交范围,帮助开发人员快速定位引入错误的提交。其工作原理是反复从版本控制系统中检出不同的提交并运行测试,将结果标记为“good”或“bad”。这个过程持续进行,直到找到引入bug的具体提交(bad commit):

git bisect特别适用于当你怀疑某个bug是由于代码库历史中的特定更改引起时,这种情况在日常开发中非常常见。

然而,并非所有的bug都能通过git bisect查找出来。尤其在编译器、运行时库以及大型复杂项目中,问题往往潜藏在难以排查的调用栈、数据流或代码路径中。在这些情况下,git bisect这种传统的工具可能会显得力不从心。

注:如果你还不熟悉git bisect的使用方法,可以参考本文后面附录中的入门示例。

在今年7月份,Go团队前技术主管Russ Cox在他的博客上发表了一篇题为“Hash-Based Bisect Debugging in Compilers and Runtimes”的文章,介绍了Go编译器和运行时团队内部使用的高级调试技术——Hash-Based Bisect。这一技术为我们提供了一种全新的问题定位方式。

在这篇文章中,我将带领大家深入了解Hash-Based Bisect这一高级调试技术,探索如何让我们自己的Go包支持这一调试技术,以及如何在日常开发中帮助我们快速定位一些难以排查的潜在问题。

1. Hash-Based Bisect是什么

前面提到过,git bisect常用于代码提交历史的回归问题排查。然而,当问题不是由提交历史引发,而是涉及程序行为的动态变化时,git bisect便显得无能为力。例如:

  • 某些代码路径或优化规则在特定运行时触发错误。
  • 测试程序在调用栈中的某些路径上表现异常。
  • 多线程或并行执行中,因运行时调度导致的问题。

Hash-Based Bisect正是为了解决这些问题而设计的。它突破了静态版本的局限,将调试范围扩展到了动态行为层面。

那么Hash-Based Bisect究竟是什么技术呢?它是一种基于哈希值和二分搜索的调试技术,旨在快速定位复杂程序中导致问题的最小变化点集合。通过为代码中的变化点(如函数、行号或调用栈)生成唯一的哈希值,该技术将程序行为映射到这些标识符上。接着,通过逐步启用或禁用特定变化点,结合测试程序的运行结果,递归缩小问题范围,最终定位问题根源(某几行代码甚至是某一行代码):

与git bisect专注于找到引入错误的提交不同,基于散列的bisect不会去遍历版本历史,而是直接对代码的结构和执行流进行操作,其调试的结果也不会与特定提交相关,而是与代码与特定执行路径或功能的交互相关,即精确定位特定的代码行,函数调用,甚至是触发失败的调用堆栈

下面我们再来仔细说明一下该技术的工作原理。

2. Hash-Based Bisect的工作原理

Hash-Based Bisect的核心在于利用哈希值为程序的变化点(如函数、代码行、调用栈等)分配唯一标识,并通过二分搜索算法,逐步缩小问题范围。它通过动态启用或禁用这些变化点,结合测试结果判断问题是否被触发,从而定位导致问题的最小变化集。

这个方法有两个关键要素:

  • 变化点的唯一标识

在Russ Cox的文章中,他提及了一些传统的二分方法,比如List-Based Bisect-Reduce、Counter-Based Bisect-Reduce等,但这些方法存在编号顺序不稳定、多变化点调试困难、扩展性有限以及不适合并发或动态场景等问题。

而通过哈希函数生成变化点的标识,确保无论代码执行顺序、环境或并发情况如何,变化点的标识始终唯一且稳定的。同时输入更为简洁,通过简短的哈希模式(如001+110),避免长列表或复杂编号,并且可适配多种问题类型(优化规则、运行时行为、动态调用栈等)。

  • 二分搜索

利用二分搜索算法在运行时动态启用和禁用变化点,高效缩小问题范围,减少需要手动排查的复杂度。

下面我们再通过Hash-Based Bisect的典型工作流程来进一步理解它的原理。

首先是定义变化点

将程序中可能导致问题的变化点抽象出来,比如:

  • 函数(函数名、文件路径)
  • 代码行(文件路径和行号)
  • 调用栈(运行时捕获)

接下来,生成变化点的唯一哈希值

以Go当前的hash-based bisect工具以及支持该工具调试的Go包为例,对于每个变化点,Go包需要通过bisect.Hash方法生成哈希值,用于唯一标识。例如:

id := bisect.Hash("foo.go", 10) // 生成foo.go文件第10行的唯一标识。

第三步,利用二分搜索进行自动的递归测试。具体来说,就是通过二分搜索逐步启用或禁用变化点:

  • 启用一个变化点集合,运行测试程序,观察是否触发问题。
  • 根据测试结果缩小范围,继续递归,直到找到最小变化点集合。

最后,报告变化点,即最终输出导致问题的最小变化集,帮助开发者快速定位问题。

Russ Cox文章中给了一个“某个函数的编译优化规则导致测试失败”的例子,例子中包含一组数学函数:

add, cos, div, exp, mod, mul, sin, sqr, sub, tan

要针对这个问题场景使用hash-based bisect进行调试,第一步就是要定义函数变化点,并为每个变化点生成唯一哈希值标识:

add: 00110010
cos: 00010000
sin: 11000111
...

然后启用二分搜索,利用Hash-Based Bisect工具依次禁用某些函数的优化,逐步缩小范围。例如:

第一步:禁用add, cos, div, exp, mod,测试通过。
第二步:禁用mul, sin, sqr, sub, tan,测试失败。
第三步:进一步细分,最终定位sin为导致问题的函数。开发者只需检查该函数的优化规则即可解决问题。

原文章中,Russ Cox利用函数变化点哈希值的位后缀构建了一颗二叉树(如下图),并利用后缀模式的不同进行问题定位:


图来自Russ Cox博客

了解了大致的工作原理后,我们再来看看Hash-Based Bisect在Go项目中的使用现状。

3. Hash-Based Bisect在Go项目中的使用现状

目前Hash-Based Bisect已经成为Go项目编译器和运行时的重要调试工具之一,其工具链(golang.org/x/tools/cmd/bisect)和库(golang.org/x/tools/internal/bisect)提供了强大的功能支持,帮助Go团队在编译器开发、运行时库升级和语言特性修改等场景下快速定位问题。

Go实现的hash-based bisect调试技术包含两部分:

bisect命令行工具可用于驱动测试运行(如go test)并自动化调试过程,支持灵活的模式定义(如-godebug、-compile选项),结合用户输入定位问题点。

  • golang.org/x/tools/internal/bisect包

该包为库和工具开发者提供一个接口,轻松实现与bisect工具的集成。并且提供了哈希生成、启用判断和变化点报告等功能,适配复杂调试需求。

上述工具目前在Go编译器的SSA(静态单赋值)后端开发、Go运行时库升级(比如Go 1.23的Timer Stop/Reset的新实现)以及语言特性的修改(比如loopvar语义变更)等方面都有重要的应用,大大提高了Go团队在定位复杂问题时的调试效率。

以上工具和包在Go项目中已经演化多年,颇为成熟。Russ Cox已经发起提案#67140,旨在将golang.org/x/tools/internal/bisect包发布为标准库debug/bisect包,这样编译器、运行时、标准库甚至标准库之外的包都可以基于它提供的功能实现与bisect工具的兼容,并利用bisect工具实现基于变更点hash值的高级调试。

讲到这里,屏幕前的你是否已经感到“迫不及待”了呢?这样优秀的工具!我们现在能否使用它?是否可以将其应用于我们自己的Go包的调试过程中呢?接下来,我就来用一个示例演示一下如何让我们自己的包支持Go bisect工具,以帮助我们提升调试效率。

4. 让你的库支持Hash-Based Bisect调试

要利用bisect调试技术,我们首先要解决的是bisect包位于internal中的问题,好在Russ Cox在实现bisect包时考虑了这个问题,bisect包没有任何外部依赖,连Go标准库都不依赖,这样避免了后续变为debug/bisect后导致标准库循环依赖的问题。现在,我们可以将它直接copy出来,放到我们自己的工程中使用。

下面是我准备的示例的目录结构:

$tree -F hash-based-bisect/bisect-demo
hash-based-bisect/bisect-demo
├── bisect/
│   └── bisect.go
├── foo/
│   ├── foo.go
│   └── foo_test.go
└── go.mod

其中bisect目录下的bisect.go来自github.com/golang/tools/blob/master/internal/bisect/bisect.go,foo包是我们这次要调试的目标包,我们先来看看foo.go的代码:

// bisect-demo/foo/foo.go

package foo

import (
    "bisect-demo/bisect"
    "flag"
)

var (
    bisectFlag = flag.String("bisect", "", "bisect pattern")
    matcher    *bisect.Matcher
)

// Features represents different features that might cause issues
const (
    FeatureRangeIteration  = "range-iteration"  // Using range vs classic for loop
    FeatureConcurrentLogic = "concurrent-logic" // Adding concurrent modifications
)

func Init() {
    flag.Parse()
    if *bisectFlag != "" {
        matcher, _ = bisect.New(*bisectFlag)
    }
}

func ProcessItems(items []int) []int {
    result := make([]int, 0, len(items))

    // First potential problematic change: different iteration approach
    id1 := bisect.Hash(FeatureRangeIteration)
    if matcher == nil || matcher.ShouldEnable(id1) {
        if matcher != nil && matcher.ShouldReport(id1) {
            println(bisect.Marker(id1), "enabled feature:", FeatureRangeIteration)
        }
        // Potentially problematic implementation using range
        for i := range items {
            result = append(result, items[i]*2)
        }
    } else {
        // Correct implementation using value iteration
        for _, v := range items {
            result = append(result, v*2)
        }
    }

    // Second potential problematic change: concurrent modifications
    id2 := bisect.Hash(FeatureConcurrentLogic)
    if matcher == nil || matcher.ShouldEnable(id2) {
        if matcher != nil && matcher.ShouldReport(id2) {
            println(bisect.Marker(id2), "enabled feature:", FeatureConcurrentLogic)
        }
        // Potentially problematic implementation with concurrency
        for i := 0; i < len(result); i++ {
            go func(idx int) {
                result[idx] += 1 // Race condition
            }(i)
        }
    }

    return result
}

大家可以结合前面提及的Hash-Based Bisect的典型工作流程来理解上面的代码。

首先,我们模拟可能导致问题的两个功能特性并定义了变化点,变化点由特性标识符的hash值标识,这里我们定义的特性标识符为:

const (
    // 使用有意义的特性名称作为 hash 的输入
    FeatureRangeIteration  = "range-iteration"  // 使用 range vs 经典 for 循环
    FeatureConcurrentLogic = "concurrent-logic" // 添加并发修改逻辑
)

接下来,对于每个可能有问题的变化点,都遵循相同的模式:

// 1. 计算特性的唯一Hash值
id1 := bisect.Hash(FeatureRangeIteration)

// 2. 检查是否应该启用该特性
if matcher == nil || matcher.ShouldEnable(id1) {
    // 3. 如果需要,报告该特性被启用
    if matcher != nil && matcher.ShouldReport(id1) {
        println(bisect.Marker(id1), "enabled feature:", FeatureRangeIteration)
    }

    // 4. 执行可能有问题的实现
    for i := range items {
        result = append(result, items[i]*2)
    }
} else {
    // 5. 执行正确的实现
    for _, v := range items {
        result = append(result, v*2)
    }
}

这里对matcher == nil的检查算是一个小优化:当不在bisect调试模式时,matcher为nil。此时我们直接启用所有特性,不需要计算hash和调用其他方法。

代码中的ShouldEnable()决定是否启用该特性的代码,ShouldReport() 决定是否需要报告该特性被启用。这两个可能返回不同的值,尤其是在bisect搜索最小失败集合时。

Marker()用于生成标准格式的匹配标记,这些标记会被bisect工具用来识别和追踪启用了哪些特性,标记会在最终输出中被移除,只显示实际的描述文本。

这里还有一个接收bisect pattern的设置,我们是通过命令行参数来接收bisect每次传给foo包的Pattern的,这里我们在Init函数,而不是init函数中调用Parse,是因为如果在init函数中调用Parse,会干扰go test测试框架,导致出现类似“flag provided but not defined: -test.paniconexit0”的测试执行错误。

下面是foo_test.go的代码:

// bisect-demo/foo/foo_test.go

package foo

import (
    "flag"
    "testing"
    "time"
)

func TestMain(m *testing.M) {
    flag.Parse()
    Init()
    m.Run()
}

func TestProcessItems(t *testing.T) {
    input := []int{1, 2, 3, 4, 5}
    result := ProcessItems(input)

    // Wait for all goroutines to complete
    time.Sleep(1000 * time.Millisecond)

    // Verify results
    if len(result) != len(input) {
        t.Fatalf("got len=%d, want len=%d", len(result), len(input))
    }

    // Check if results are correct
    for i, v := range input {
        expected := v * 2
        if result[i] != expected {
            t.Errorf("result[%d] = %d, want %d", i, result[i], expected)
        }
    }
}

显然为了foo包能成功获取命令行参数,我们重写了TestMain,在其中调用了foo.Init函数。

接下来,我们就来执行一下bisect工具,对foo包进行一下调试,你可以通过go install golang.org/x/tools/cmd/bisect@latest安装bisect。此外下面bisect命令行中的PATTERN是一个“占位符”,bisect命令会识别该“占位符”,并将其替换为相应的字符串,这个在bisect的执行过程中你也会看到:

// 在hash-based-bisect/bisect-demo/foo目录下执行

$bisect -v go test -v -args -bisect=PATTERN
bisect: checking target with all changes disabled
bisect: run: go test -v -args -bisect=n... ok (0 matches)
bisect: matches:
bisect: run: go test -v -args -bisect=n... ok (0 matches)
bisect: matches:
bisect: checking target with all changes enabled
bisect: run: go test -v -args -bisect=y... FAIL (2 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: run: go test -v -args -bisect=y... FAIL (2 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: target succeeds with no changes, fails with all changes
bisect: searching for minimal set of enabled changes causing failure
bisect: run: go test -v -args -bisect=+0... ok (1 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
bisect: run: go test -v -args -bisect=+0... ok (1 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
bisect: run: go test -v -args -bisect=+1... FAIL (1 matches)
bisect: matches:
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: run: go test -v -args -bisect=+1... FAIL (1 matches)
bisect: matches:
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: confirming failing change set
bisect: run: go test -v -args -bisect=v+x3f... FAIL (1 matches)
bisect: matches:
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: run: go test -v -args -bisect=v+x3f... FAIL (1 matches)
bisect: matches:
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
bisect: FOUND failing change set
--- change set #1 (enabling changes causes failure)
enabled feature: concurrent-logic
---
bisect: checking for more failures
bisect: run: go test -v -args -bisect=-x3f... ok (1 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
bisect: run: go test -v -args -bisect=-x3f... ok (1 matches)
bisect: matches:
[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
bisect: target succeeds with all remaining changes enabled

简单解读一下这个bisect调试过程的输出。

bisect执行分为几个阶段:

  • 初始检查阶段

首先用-bisect=n禁用所有变更进行测试 → 测试通过(ok)
然后用-bisect=y启用所有变更进行测试 → 测试失败(FAIL)

这表明程序在没有任何变更时是正常的,但启用所有变更后会失败。

启用所有变更时观察到两个特性:

[bisect-match 0xcf0b8943315a7804] enabled feature: range-iteration
[bisect-match 0x4d642a7960e4693f] enabled feature: concurrent-logic
  • 二分查找阶段

测试+0(启用第一个变更:range-iteration)→ 测试通过(ok)
测试+1(启用第二个变更:concurrent-logic)→ 测试失败(FAIL)

这个过程帮助定位到具体是哪个变更导致了失败。

  • 确认阶段

使用v+x3f 模式再次确认 → 测试失败(FAIL)
明确找到了导致失败的变更集合:

--- change set #1 (enabling changes causes failure)
enabled feature: concurrent-logic
---
  • 最终验证

使用-x3f 模式(禁用确认的问题变更)进行测试 → 测试通过(ok)
确认启用其他所有变更(除了concurrent-logic)时程序都能正常运行。

从中得出调试结论:bisect工具成功定位到问题出在concurrent-logic特性上,range-iteration特性是安全的,不会导致测试失败。问题明确是在并发逻辑中的“故意”逻辑导致的,这符合我们的代码实现中的预期问题(在 concurrent-logic 特性中,我们确实故意修改了数据)。

5. 小结

在本文中,我们深入探讨了Hash-Based Bisect这一先进的调试技术,特别是在Go语言项目中的应用。Hash-Based Bisect通过为代码的变化点生成唯一的哈希值,结合二分搜索算法,帮助开发者快速定位复杂程序中的问题,超越传统的git bisect方法。我们还详细介绍了其工作原理、在Go项目中的现状,以及如何将这一技术集成到自己的Go库中,以提升调试效率。也许这里的示例也许并不恰当,但已经达成了我向你展示如何使用bisect工具和bisect包的目的。

尽管Hash-Based Bisect在定位复杂问题上表现出色,但感觉其当前设计仍存在一些不足,这些不足可能会影响开发者的使用体验,尤其是在将其集成到Go包或项目时,这个不足主要体现在对代码的侵入性上。为了支持Hash-Based Bisect,Go包需要显式实现与bisect工具交互的协议,包括支持从命令行或环境变量接收bisect传入的模式(pattern);需要在代码中创建bisect.Matcher对象,并调用ShouldEnable和ShouldReport接口来管理变化点;代码中必须为潜在变化点显式生成唯一的哈希值,并根据需要启用或禁用。

这种显式集成导致代码逻辑被调试相关代码“污染”,增加了代码复杂度和维护成本。对于一些简单的库或项目,开发者可能不愿为调试需求增加这种负担。

在\$GOROOT/src/cmd/compile/internal/base中,编译器相关代码就将bisect封装到了一个HashDebug结构中,一定程度上减少了代码的侵入深度以及手动集成的工作量。

此外,golang.org/x/tools/internal/bisect包尚未正式变为debug/bisect,后续其API是否会发生变化,尚不得而知,本文中的示例代码不保证在后续的Go版本调整后依然能够正确运行。

本文涉及的源码可以在这里下载。

6. 参考资料

7. 附录:git bisect使用示例

假设你有一个Go语言项目,并且发现最近的某次提交引入了一个问题(例如,某个测试用例失败了)。你希望使用git bisect找到引入该问题的具体提交。

你的项目目录设计如下:

my-go-project/
├── main.go
└── main_test.go

我们来建立这个示例项目:

// 在hash-based-bisect/git-bisect下面执行
$mkdir my-go-project
$cd my-go-project
$git init

创建main.go:

// main.go
package main

func main() {
    println("Hello, world!")
}

func Add(a, b int) int {
    return a + b
}

提交变更:

$git add main.go
git commit -m "Initial commit with Add function"
[master (root-commit) 16f8736] Initial commit with Add function
 1 file changed, 9 insertions(+)
 create mode 100644 main.go

创建main_test.go:

// main_test.go
package main

import "testing"

func TestAdd(t *testing.T) {
    if Add(2, 3) != 5 {
        t.Error("Expected 5, got something else")
    }
}

提交变更:

$git add main_test.go
git commit -m "Add test for Add function"
[master b7b3c44] Add test for Add function
 1 file changed, 9 insertions(+)
 create mode 100644 main_test.go

故意引入一个bug并提交变更:

$sed -i 's/return a + b/return a - b/' main.go
$git commit -am "Introduce a bug in Add function"
[master 977e647] Introduce a bug in Add function
 1 file changed, 1 insertion(+), 1 deletion(-)

添加一些其他提交(无关的变更):

$echo "// Just a comment" >> main.go
$git commit -am "Add a comment"
[master 25f88b0] Add a comment
 1 file changed, 2 insertions(+)

这里列出上面所有commit的list,便于后续对照:

$git log --oneline
25f88b0 (HEAD -> master) Add a comment
977e647 Introduce a bug in Add function
b7b3c44 Add test for Add function
16f8736 Initial commit with Add function

接下来,我们就可以演示git bisect了,先来演示一下手工bisect。

启动git bisect模式:

$git bisect start

标记当前最新提交为bad:

$git bisect bad

标记首次提交为good:

$git bisect good 16f8736
Bisecting: 0 revisions left to test after this (roughly 1 step)
[977e647e7461c4c03ee25e53728dd743af925f17] Introduce a bug in Add function

我们看到git bisect自动切换到一个中间的提交,我们需要验证这次中间提交是否能通过测试:

$go test
--- FAIL: TestAdd (0.00s)
    main_test.go:7: Expected 5, got something else
FAIL
exit status 1
FAIL    github.com/bigwhite/experiments/hash-based-bisect/git-bisect/my-go-project  0.006s

测试失败,我们将该提交标记为bad:

$git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[b7b3c444f0fd55086e6ce36fb543a136a1611b61] Add test for Add function

git bisect又切换到了另外一个中间提交,我们用go test验证是否能通过:

$go test
PASS
ok      github.com/bigwhite/experiments/hash-based-bisect/git-bisect/my-go-project  0.005s

测试通过,我们将这个中间提交标记为good:

$git bisect good
977e647e7461c4c03ee25e53728dd743af925f17 is the first bad commit
commit 977e647e7461c4c03ee25e53728dd743af925f17
Author: Tony Bai <bigwhite.cn@aliyun.com>
Date:   Fri Nov 24 13:27:08 2024 +0800

    Introduce a bug in Add function

:100644 100644 e357c05d933724eb8b7c1aafee34b8f95913355e e65baa0414a2a1f983379c23ac549b7d8b056db3 M  main.go

我们看到:git bisect找到了一个bad commit,并显示“977e647e7461c4c03ee25e53728dd743af925f17 is the first bad commit”。

结束git bisect模式:

$git bisect reset

上面的过程可以使用git bisect run进行自动化,而无需中间手动多次的执行go test和标记,下面是一个等价的git bisect过程:

$git bisect start

$git bisect bad

$git bisect good 16f8736
Bisecting: 0 revisions left to test after this (roughly 1 step)
[977e647e7461c4c03ee25e53728dd743af925f17] Introduce a bug in Add function

$git bisect run go test
running go test
--- FAIL: TestAdd (0.00s)
    main_test.go:7: Expected 5, got something else
FAIL
exit status 1
FAIL    github.com/bigwhite/experiments/hash-based-bisect/git-bisect/my-go-project  0.006s
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[b7b3c444f0fd55086e6ce36fb543a136a1611b61] Add test for Add function
running go test
PASS
ok      github.com/bigwhite/experiments/hash-based-bisect/git-bisect/my-go-project  0.006s
977e647e7461c4c03ee25e53728dd743af925f17 is the first bad commit
commit 977e647e7461c4c03ee25e53728dd743af925f17
Author: Tony Bai <bigwhite.cn@aliyun.com>
Date:   Fri Nov 24 13:27:08 2024 +0800

    Introduce a bug in Add function

:100644 100644 e357c05d933724eb8b7c1aafee34b8f95913355e e65baa0414a2a1f983379c23ac549b7d8b056db3 M  main.go
bisect run success

$git bisect reset
Previous HEAD position was b7b3c44 Add test for Add function
Switched to branch 'master'

我们看到通过git bisect run可以更快速地定位问题,而无需中间的手工操作,这是我们日常开发中主要使用的bisect手段!


Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时,我们也会加强代码质量和最佳实践的分享,包括如何编写简洁、可读、可测试的Go代码。此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
  • Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

代码提交者的代码评审通关指南[译]

本文永久链接 – https://tonybai.com/2024/10/11/the-cl-author-guide-to-getting-through-code-review

Google在软件工程领域对IT界做出了卓越的贡献,从《Google软件工程》,到Google Style Guides,再到The Change Author’s Guide。这些实践参考不仅提升了软件工程的标准,也为全球IT行业的发展提供了宝贵的资源和指导。由于Go是Google开源的,其cl review基本上是遵循了Google内部的标准和实践,可以帮助开发人员更快地完成审核并获得更高质量的结果。因此在这篇文章中,我翻译一下The Change Author’s Guide,供大家参考。

The Change Author’s Guide分为三部分,由于每一部分篇幅都不多,这里就放在一起了。本次翻译是基于Google Engineering Practices Documentation的commit 3bb3ec25b3b0199f4940b1aa75f0ac5c5753301c进行的。

注:Google内部使用的术语CL代表“变更列表(changelist)”,指的是一个自包含的更改,该更改已经提交到版本控制系统或正在进行代码评审。其他组织通常称之为“变更”、“补丁”或“拉取请求(PR)”。


1. 编写良好的CL描述

CL描述是变更的公开记录,重要的是它能够传达以下信息:

  • 做了什么 变更?这应该总结主要的变化,使读者在不需要阅读整个CL的情况下了解正在发生的变化。
  • 为什么要做出这些变更?作为作者,你在做出这个变更时有什么背景?以及你做出的那些在源代码中无法反映出来的决策?等等。

CL描述将成为我们版本控制历史的一部分,未来可能会被数百人阅读。

未来的开发人员将根据描述搜索你的CL。未来某人可能因为对其相关性有模糊的记忆而寻找你的变更,但没有具体细节。如果所有重要信息都在代码中而非描述中,他们将更难找到你的CL。

而且,在他们找到CL后,是否能够理解为什么做出这个变更?阅读源代码可能会揭示软件在做什么,但可能不会揭示其存在的原因,这可能会使未来的开发人员更难知道他们是否可以移动切斯特顿的栅栏(Chesterton’s fence)

译注:切斯特顿的栅栏是一种启发式方法,由G.K.切斯特顿提出,旨在告诫人们在改变任何系统之前,应先了解该系统存在的原因和功能,否则可能会造成更大的问题。

一个编写良好的CL描述将帮助这些未来的工程师——有时,也包括你自己!

1.1 第一行(first line)

  • 简短总结所做的内容。
  • 使用完整句子,以命令的形式书写。
  • 后面跟一个空行。

CL描述的第一行应该是对具体做了什么的简短总结,后面跟一个空行。这是出现在版本控制历史摘要中的内容,因此应该提供足够的信息,使未来的代码搜索者无需阅读你的CL或其整个描述就能理解你的CL实际上做了什么,或与其他CL的不同之处。也就是说,第一行应该独立存在,让读者更快地浏览代码历史。

尽量保持第一行简短、重点突出且切中要点。清晰性和对读者的实用性应是最重要的。

按照传统,CL描述的第一行应该是一个完整的句子,并以命令形式书写(即祈使句)。例如,应该说“Delete the FizzBuzz RPC and replace it with the new system.”,而不是“Deleting the FizzBuzz RPC and replacing it with the new system.”,不过,你不必将其余的描述写成祈使句。

1.2 主体信息要丰富

第一行应该是简短且重点突出的摘要,而其余的描述应详细说明并包括读者理解变更列表所需的任何补充信息。它可能包括对正在解决的问题的简要描述,以及为什么这是最佳方法。如果该方法有任何不足之处,应该指出。如果有相关信息也要列出,包含背景信息,如错误编号、基准测试结果和设计文档链接等。

如果你包含外部资源的链接,请考虑由于访问限制或保留政策,未来读者可能无法看到这些链接。在可能的情况下,包含足够的上下文,以便审查者和未来读者理解CL。

即使是小的CL也值得关注细节。将CL放在上下文中。

1.3 不好的CL描述

“Fix bug”是一个不充分的CL描述。什么bug?你做了什么来修复它?其他类似的不好的描述包括:

  • “Fix build.”
  • “Add patch.”
  • “Moving code from A to B.”
  • “Phase 1.”
  • “Add convenience functions.”
  • “kill weird URLs.”

其中一些都是取自真实的CL描述。虽然简短,但它们没有提供足够的有用信息。

1.4 良好的CL描述

以下是一些好的CL描述示例。

1.4.1 功能变更

示例:

RPC: Remove size limit on RPC server message freelist.

Servers like FizzBuzz have very large messages and would benefit from reuse. Make the freelist larger, and add a goroutine that frees the freelist entries slowly over time, so that idle servers eventually release all freelist entries.

第一行描述了CL实际做了什么。其余的描述谈论了正在解决的问题、为什么这是一个好的解决方案以及有关具体实现的更多信息。

1.4.2 重构

示例:

Construct a Task with a TimeKeeper to use its TimeStr and Now methods.

Add a Now method to Task, so the borglet() getter method can be removed (which was only used by OOMCandidate to call borglet's Now method). This replaces the methods on Borglet that delegate to a TimeKeeper.

Allowing Tasks to supply Now is a step toward eliminating the dependency on Borglet. Eventually, collaborators that depend on getting Now from the Task should be changed to use a TimeKeeper directly, but this has been an accommodation to refactoring in small steps.

Continuing the long-range goal of refactoring the Borglet Hierarchy.

第一行描述了CL做了什么以及这是如何与过去不同的。其余的描述谈论了具体实现、CL的背景、解决方案并不理想以及可能的未来方向。它还解释了为什么这个变更被做出。

1.4.3 需要一些上下文的小CL

示例:

Create a Python3 build rule for status.py.

This allows consumers who are already using this as in Python3 to depend on a rule that is next to the original status build rule instead of somewhere in their own tree. It encourages new consumers to use Python3 if they can, instead of Python2, and significantly simplifies some automated build file refactoring tools being worked on currently.

第一句描述了实际的变更。其余的描述解释了为什么这个变更被做出,并给审查者提供了大量的上下文信息。

1.5 使用标签(tags)

标签是手动输入的label,可用于对CL进行分类。这些标签可能由工具支持,也可能只是团队惯例。

例如:

  • “[tag]“
  • “[a longer tag]“
  • “#tag”
  • “tag:”

使用标签是可选的。

添加标签时,考虑它们是否应该在CL描述的主体中或第一行中。限制在第一行中使用标签的数量,因为这可能会模糊内容。

以下是带标签和不带标签的示例:

// Tags are okay in the first line if kept short.
[banana] Peel the banana before eating.

// Tags can be inlined in content.
Peel the #banana before eating.

// Tags are optional.
Peel the banana before eating.

// Multiple tags are acceptable if kept short.
#banana #apple: Assemble a fruit basket.

// Tags can go anywhere in the CL description.
> Assemble a fruit basket.
>
> #banana #apple
// Too many tags (or tags that are too long) overwhelm the first line.
//
// Instead, consider whether the tags can be moved into the description body
// and/or shortened.
[banana peeler factory factory][apple picking service] Assemble a fruit basket.

1.6 生成的CL描述

有些CL是由工具生成的。只要有可能,它们的描述也应该遵循此处的建议。也就是说,它们的第一行应该简短、重点突出且独立,CL描述主体应包含有助于审查者和未来代码搜索者理解每个CL效果的信息细节。

1.7 提交CL前审查描述

CL在审查过程中可能会发生重大变化。在提交CL前审查CL描述是值得的,可以确保描述仍然真实反映CL的内容。

2. 小型CL

2.1 为什么要写小型的CL?

小而简单的CL有以下优点:

  • 审查速度更快。审查者更容易找到几分钟的时间来审查小CL,而不是腾出30分钟的时间来审查一个大CL。
  • 审查更彻底。 对于大变更,审查者和作者往往会因大量详细评论反复交换而感到沮丧,有时甚至会错过或忽略重要点。
  • 引入错误的可能性更小。由于你所做的更改较少,因此你和审查者更容易有效地推理CL的影响,并查看是否引入了错误。
  • 被拒绝时浪费的工作更少。 如果你写了一个巨大的CL,然后审查者表示整体方向错误,你就浪费了很多工作。
  • 更容易合并。 处理一个大CL需要很长时间,因此在合并时会遇到许多冲突,你将不得不频繁合并。
  • 更容易设计良好。 完善小变更的设计和代码质量要比完善大变更的所有细节容易得多。
  • 审查阻塞更少。 发送自包含的整体变更部分允许你在等待当前CL审查时继续编码。
  • 回滚更简单。 大CL更可能涉及在初始CL提交和回滚CL之间更新的文件,从而增加回滚的复杂性(中间的CL可能也需要回滚)。

请注意,审查者有权仅因为变更过大而直接拒绝你的变更。通常,他们会感谢你的贡献,但会要求你以某种方式将其拆分为一系列较小的变更。在你已经编写完变更后拆分它可能会花费很多时间,或者需要大量时间来争论审查者为什么应该接受你的大变更。因此,最好一开始就写小型CL。

2.2 多小算小?

一般而言,CL的合适大小是一个自包含的变更。这意味着:

  • CL进行最小变更,只解决一件事。这通常只是一个功能的一部分,而不是一次性完成整个功能。一般来说,最好宁可编写太小的CL,也不要编写太大的CL。与你的审核者合作找出可接受的尺寸。
  • CL应该包含相关的测试代码。
  • 审查者理解CL所需的一切(除未来开发外)都应包含在CL中,比如本CL的描述、现有代码库或他们已经审查过的CL。
  • 系统在CL被检查入库后仍能良好工作,适用于其用户和开发人员。
  • CL不应小到其含义难以理解。如果你添加了一个新的API,应该在同一个CL中包含对该API的使用方法,以便审查者更好地理解API将如何使用。这也能防止未使用的API被提交。

没有关于“过大”的硬性规则。100行通常是合理的CL大小,而1000行通常被认为过大,但这取决于审查者的判断。变更涉及的文件数量也会影响其“大小”。在一个文件中的200行变更可能是可以接受的,但变更分布在50个文件中的话通常会被认为过大。

请记住,尽管你从开始编写代码的那一刻起就与代码密切相关,审查者通常没有上下文。对你来说合适大小的CL可能对审查者来说会是难以接受的。若有疑问,写比你认为需要的更小的CL。审查者很少抱怨收到的CL太小。

2.3 大型CL什么时候可以?

在某些情况下,大变更并不那么糟糕:

  • 通常可以将删除整个文件视为仅一行变更,因为审查者审核它所花费的时间很少。
  • 有时,大CL是由你完全信任的自动重构工具生成的,审查者的工作只是验证并确认他们确实想要这个变更。这些CL可以更大,尽管上述一些注意事项(例如合并和测试)仍然适用。

2.4 高效地编写小型CL

如果你编写了一个小型CL,然后等待审查者批准它,再写下一个CL,那么你将浪费很多时间。因此,你需要找到一种方法,在等待审查时不会阻塞自己。这可能涉及同时处理多个项目,找到愿意立即可用的审查者,进行面对面审查,进行配对编程,或者以某种方式拆分你的CL,以便你能够立即继续工作。

2.5 拆分CL

如果存在多个相互依赖的CL时,我们通常有必要在深入编码之前从高层次考虑如何拆分和组织这些CL。

除了使你作为作者更容易管理和组织CL外,这也让你的代码审查者更容易,从而使你的代码审查更高效。

以下是将工作拆分为不同CL的一些策略。

2.5.1 将多个变更堆叠在一起

拆分CL的一种方法是编写一个小CL,发送审查,然后立即开始编写一个基于第一个CL的另一个CL。大多数版本控制系统都允许你以某种方式做到这一点。

2.5.2 按文件拆分

另一种拆分CL的方法是按文件分组,这些文件需要不同的审查者,但其他方面是自包含的变更。

例如:你发送一个CL用于对protocol buffer修改,另一个CL用于对使用该proto的代码的更改。你必须在code CL之前提交proto CL,但它们可以同时接受审查。如果这样做,你可能想通知两组审查者你编写的另一个CL,以便他们了解你的变更的上下文。

另一个例子:你发送一个CL用于代码变更,另一个用于使用该代码的配置或实验;如果有必要,这也更容易回滚,因为配置/实验文件有时比代码变更更快地推送到生产环境。

2.5.3 横向拆分

考虑创建共享代码或存根,以帮助隔离技术栈各层之间的变更。这不仅有助于加快开发速度,还鼓励层之间的抽象。

例如:你创建了一个计算器应用程序,其中有客户端、API、服务和数据模型层。共享的proto signature可以将服务层和数据模型层相互抽象。类似地,API存根可以将客户端代码的实现与服务代码分开,使它们能够独立演进。类似的思路也可以应用于更细粒度的函数或类级别的抽象。

2.5.4 纵向拆分

与分层的横向方法相对应,你可以将代码拆分为更小、全栈、垂直的功能。这些功能中的每一个都可以独立并行实现。这使得一些轨道能够继续前进,而其他轨道则在等待审查或反馈。

回到我们在横向拆分所举的计算器示例。你现在想支持新的运算符,如乘法和除法。你可以通过将乘法和除法实现为独立的纵向特性或子功能来拆分,尽管它们可能有一些重叠,例如共享按钮样式或共享验证逻辑。

2.5.5 横向和纵向拆分

为了进一步发展,你可以结合这些方法并制定一个实施计划,其中每个单元都是独立的CL。从模型(底部)开始,逐渐推进到客户端:

2.6 将重构与功能变更分开

通常最好将重构与功能变更或错误修复分开。例如,移动和重命名一个类应该与修复该类中的错误放在不同的CL中。这样,审查者更容易理解每个CL引入的变更。

不过,小的清理工作,例如修复局部变量名称,可以包含在功能变更或错误修复CL中。开发人员和审查者需判断何时重构的规模过大,以至于将其包含在当前CL中会使审查更加困难。

2.7 将相关的测试代码放在同一个CL中

CL应该包括相关的测试代码。请记住,这里的“小”指的是CL应该聚焦且不是单纯的行数问题。

所有谷歌的变更都需要测试。

添加或更改逻辑的CL应该伴随新的或更新的测试,以验证新行为。纯重构CL(不打算改变行为)也应有测试覆盖;理想情况下,这些测试已经存在,但如果没有,你应添加它们。

独立的测试修改可以先放入单独的CL,类似于重构准则。这包括:

  • 用新测试验证预先存在的提交代码。

确保重要逻辑被测试覆盖。增加对受影响代码后续重构的信心。例如,如果你想重构没有测试覆盖的代码,提交测试CL可以在提交重构CL之前可以验证受测行为在重构前后是否保持不变。

  • 重构测试代码(例如,引入助手函数)。
  • 引入更大的测试框架代码(例如,集成测试)。

2.8 不要破坏构建

如果你有多个相互依赖的CL,你需要找到一种方法,在每个CL提交后确保整个系统保持正常工作。否则,你可能会在CL提交之间破坏所有同事的构建,影响大家几分钟(或在稍后的CL提交中出现意外问题时,甚至更长时间)。

2.9 无法做到足够小

有时你会遇到CL必须很大的情况。这种情况很少发生。练习编写小CL的作者几乎总能找到将功能分解为一系列小变更的方法。

在编写大CL之前,请考虑是否可以先进行仅重构的CL,以便为更干净的实现铺平道路。与你的团队成员交谈,看看是否有人对如何将功能实现为小CL发表看法。

如果所有这些选项都失败(这应该非常少见),那么请提前获得审查者的同意,以审核大CL,以便他们对即将到来的内容有所警觉。在这种情况下,预计审查过程会比较漫长,要警惕不要引入错误,并更加细致地编写测试。

3. 如何处理审查者的意见

当你将代码提交(CL)发送审查时,审查者可能会对你的代码提出多个意见。以下是一些处理审查者意见的有用建议。

3.1 不要把它视为针对个人

审查的目标是维护我们的代码库和产品的质量。当审查者对你的代码提出批评时,请将其视为他们试图帮助你、代码库和谷歌的一种方式,而不是对你或你能力的个人攻击。

有时,审查者可能会感到沮丧,并在评论中表达这种沮丧。虽然对于审查者来说,这不是一个好的做法,但作为开发人员,你应该对此有所准备。问问问自己:“审查者想要向我传达的建设性意见是什么?”然后按照他们实际所说的那样进行操作。

绝不要对代码审查意见做出愤怒的回应。 这是一种严重违反职业礼仪的行为,将在代码审查工具中留下永久记录。如果你太愤怒或烦恼而无法友好地回应,请离开电脑一段时间,或做些其他事情,直到你冷静下来再礼貌地回复。

一般来说,如果审查者没有以建设性和礼貌的方式提供反馈,请当面与他们解释。如果无法面对面或视频通话,那么可以私下发一封邮件给他们。以友好的方式解释你不喜欢的地方以及希望他们做出怎样的改变。如果他们在这次私人讨论中以非建设性的方式回应,或者没有达到预期效果,请酌情上报给你的经理。

3.2 修正代码

如果审查者表示他们不理解你代码中的某些内容,你的第一反应应该是澄清代码本身。如果代码无法澄清,请添加代码注释,解释代码存在的原因。如果某个注释似乎没有意义,你再在代码审查工具中做解释。

如果审查者不理解你的某段代码,未来其他读者也可能无法理解。写一条在代码审查工具中的回应并不能帮助未来的代码读者,但澄清代码或添加代码注释则能帮助他们。

3.3 协作思考

编写代码变更(CL)可能需要大量工作。最终将其发送审查,感觉一切都完成了,可能会很令人满意,但收到要求更改的评论时也可能会感到沮丧,尤其是当你不同意这些评论时。

在这样的时刻,请花点时间退后一步,考虑审查者是否提供了有价值的反馈,能帮助代码库和谷歌。你首先要问自己,“我理解审查者所要求的吗?”

如果你无法回答这个问题,请向审查者寻求澄清。

然后,如果你理解评论但不同意,重要的是要协作思考,而不是对抗性或防御性思考:

Bad: “No, I’m not going to do that.”
Good: "I went with X because of [these pros/cons] with [these tradeoffs]
My understanding is that using Y would be worse because of [these reasons].
Are you suggesting that Y better serves the original tradeoffs, that we should
weigh the tradeoffs differently, or something else?"

请记住,礼貌和尊重始终应放在首位。如果你不同意审查者的观点,请寻找协作的方式:寻求澄清、讨论优缺点,并解释为什么你处理事情的方法更适合代码库、用户和/或谷歌。

有时,你可能知道一些审查者不知道的关于用户、代码库或CL的信息。在适当的地方修复代码,并与审查者进行讨论,提供更多上下文。通常,你可以根据技术事实与审查者达成某种共识。

3.4 解决冲突

解决冲突的第一步始终是尝试与审查者达成共识。如果无法达成共识,请参阅代码审查标准,其中提供了在这种情况下应遵循的原则。


Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时,我们也会加强代码质量和最佳实践的分享,包括如何编写简洁、可读、可测试的Go代码。此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
  • Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言进阶课 AI原生开发工作流实战 从 0 开始构建 Agent Harness Go语言精进之路1 Go语言精进之路2 Go语言第一课 Go语言编程指南
商务合作请联系bigwhite.cn AT aliyun.com
这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats