【实用系列】Golang代码注释自动修复工具

最近，我发布了github上的第一个开源代码库：godoc-repair，地址为：https://github.com/xiaoyuanhao/godoc-repair。这是一个用于修复Golang代码注释的工具，个人觉得特别实用，可以为修复代码注释节省大量的时间成本。

背景

事情是这样的。最近由于代码规范要求对Golang代码注释的要求加强了，对于“Exported（对外暴露）”的代码，要求增加注释，且需要按照godoc规定格式进行代码注释书写。

我呢，是一个爱写注释的人。但，写的很多注释不符合godoc规定的格式。于是乎，被自动扫描工具扫出了500多处需要修复的代码。如果我一处一处地修复，不仅会干特别重复的事情，而且这将浪费我大量的时间，预估至少需要耗费半天进行修复。

对于我这个“懒人”来说，特别不愿意干这种重复的事情。突然灵光一现，会不会有什么自动修复的工具？如果有，我就不需要一处一处地去修复。搜了搜，果然是有的。网上找到了godoc自动生成工具：godoc-generate。这是一个用于自动生成代码注释的工具，它会在所有“Exported”内容前加一行注释：“... missing godoc.（这里缺少一个注释）”

虽然godoc-genenrate可以自动添加一行注释，虽然直接用它能够逃避工具的扫描。但对我来说，它不符合要求，因为我是要修复代码注释的格式，而它是自动生成一条预留的注释内容。

那咋办嘞？作为程序员来说，按需改呗。这就是godoc-repair的由来，根据我设定的待修复内容，自动修复成规定的注释格式。

工具介绍

这里，简单介绍下godoc-repair，主要介绍下它可以修复的内容。

写在前面

• 建议大家好好写注释，写好注释很重要。
• 工具只能按照我遇到的一些case进行内容修复，可能覆盖不全大家的case。
• 工具修复后的内容，建议大家进行double check。
• 欢迎大家按照自身情况，提交代码~

覆盖用例

以下说明godoc-repair能够覆盖的情况：

缺少名字

修复前

// camel case
type CamelCase struct {}

修复后

// CamelCase camel case
type CamelCase struct {}

名字后带了冒号

修复前

// CamelCase: camel case
type CamelCase struct {}
//CamelCase2: camel case
type CamelCase2 struct {}

修复后

// CamelCase camel case
type CamelCase struct {}
// CamelCase2 camel case
type CamelCase2 struct {}

缺少注释

缺少注释的情况比较特殊。默认情况下，维持了godoc-generate的方式，预留了注释内容，格式为：

// %s missing godoc.

'%s'会自动添加上名字。

修复前

type CamelCase struct {}

修复后

// CamelCase missing godoc.
type CamelCase struct {}

还有一种情况。如果名字本身就很清晰，我想挺多同学会不写注释。对于这种情况，工具会将名字按照【驼峰】格式拆解成单个单词作为注释描述内容。

修复前

type CamelCase struct {}

修复后

// CamelCase camel case
type CamelCase struct {}

缺少注释描述

与“缺少注释”一样，也可以使用【驼峰】格式拆解为注释描述内容。

修复前

// CamelCase
type CamelCase struct {}
//CamelCase2
type CamelCase2 struct {}

修复后

// CamelCase camel case
type CamelCase struct {}
// CamelCase2 camel case
type CamelCase2 struct {}

工具安装与示例

godoc-repair怎么安装，很简单，执行下面的命令即可：

go install github.com/xiaoyuanhao/godoc-repair

工具怎么使用，示例如下：

go-repair --code-path /path/to/your/code
// example: go-repair --code-path ./example --auto-description

支持的参数介绍如下：

• --format，用于配置自定义预留内容。
• --code-path，用于配置需要修复的代码目录（目前不支持单文件修复），默认为当前目录。
• --auto-description，按照名字的【驼峰】格式，自动添加注释描述内容。

总结

欢迎大家尝试godoc-repair，这是我在github上建立的第一个代码库。凡事都有第一次，希望它有点用。一起加油吧，各位。

文章首发于“元坑昊思迹”公众号，欢迎关注，了解更多元坑昊的所思所想。

元坑昊思迹公众号