Go 开发工具：VS Code 调试与文档注释

前置：创建模块、运行测试。调试器用于观察一次执行；可重复验证仍写进测试。配置按 Go 扩展的 Delve 调试说明核对，JSON 已校验；本环境未执行 VS Code F5 调试，macOS 仅作平台说明，本项目不执行平台运行验证。

最小 VS Code 调试配置

在 VS Code 打开含 go.mod 的目录，安装 Go 项目维护的 Go 扩展，在 .vscode/launch.json 写入下面配置。${workspaceFolder} 是当前工作区目录。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug current module",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}",
      "cwd": "${workspaceFolder}",
      "args": [],
      "env": {}
    }
  ]
}

在 main 内可执行语句上设断点，再启动配置。当前目录须是 main 包；入口在 cmd/server 就将 program 改成 ${workspaceFolder}/cmd/server。mode=test 用于测试包；request=attach 是附加进程，不是旧笔记中的 append。普通本地 launch 不需手工开放远程监听端口。

断点不命中与工具故障

先在相同 cwd 运行 go test ./... 或 go build，编译失败先修代码。再看扩展输出中的实际工具链、dlv 路径和错误；工具安装按扩展选择当前支持的工具，不批量运行旧 gocode、guru、gometalinter 清单。确认二进制与源码一致，断点路径确实被执行。

多进程各自建立配置，入口、环境和端口不冲突，逐个验证后再使用 compounds。真实地址、凭据和个人环境放本地配置，不能把旧项目的内网地址当通用示例。

注释与生成模板

GoLand 或 goanno 的模板只是输入辅助。导出函数注释应以名称起头，解释约束、失败语义和并发安全，而不是堆出空的 receiver、param、return 标签。规则维护在注释规范，输出用Example 测试验证。

局部示例，放在实际处理标题的函数上方：

// NormalizeTitle removes surrounding whitespace. It returns an error for an empty title.

练习与自检

把课程 main.go 放进 cmd/demo，调整 program，先用 go run ./cmd/demo 确认入口，再调试。故意写错 cwd，观察相对数据路径改变。

参考解法

program 指向入口包，cwd 决定运行目录。调试成功后将发现的行为写成测试，避免只在调试会话里检查一次。

依据：Go 扩展调试文档、Go Code Review Comments。