前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >【实用系列】Golang代码注释自动修复工具

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

原创
作者头像
元坑昊
发布2022-06-24 19:38:31
1.5K0
发布2022-06-24 19:38:31
举报
文章被收录于专栏:元坑昊思迹

最近,我发布了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能够覆盖的情况:

缺少名字

修复前

代码语言:go
复制
// camel case
type CamelCase struct {}

修复后

代码语言:go
复制
// CamelCase camel case
type CamelCase struct {}

名字后带了冒号

修复前

代码语言:go
复制
// CamelCase: camel case
type CamelCase struct {}
//CamelCase2: camel case
type CamelCase2 struct {}

修复后

代码语言:go
复制
// CamelCase camel case
type CamelCase struct {}
// CamelCase2 camel case
type CamelCase2 struct {}

缺少注释

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

代码语言:javascript
复制
// %s missing godoc.

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

修复前

代码语言:go
复制
type CamelCase struct {}

修复后

代码语言:go
复制
// CamelCase missing godoc.
type CamelCase struct {}

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

修复前

代码语言:go
复制
type CamelCase struct {}

修复后

代码语言:go
复制
// CamelCase camel case
type CamelCase struct {}

缺少注释描述

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

修复前

代码语言:go
复制
// CamelCase
type CamelCase struct {}
//CamelCase2
type CamelCase2 struct {}

修复后

代码语言:go
复制
// CamelCase camel case
type CamelCase struct {}
// CamelCase2 camel case
type CamelCase2 struct {}

工具安装与示例

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

代码语言:shell
复制
go install github.com/xiaoyuanhao/godoc-repair

工具怎么使用,示例如下:

代码语言:shell
复制
go-repair --code-path /path/to/your/code
// example: go-repair --code-path ./example --auto-description

支持的参数介绍如下:

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

总结

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


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

图片
图片

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 背景
  • 工具介绍
    • 写在前面
      • 覆盖用例
        • 缺少名字
        • 名字后带了冒号
        • 缺少注释
        • 缺少注释描述
    • 工具安装与示例
    • 总结
    领券
    问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档