{"id":15930994,"url":"https://github.com/xdpcs/go-code-comment-standard","last_synced_at":"2025-03-24T18:31:40.013Z","repository":{"id":157277928,"uuid":"612584082","full_name":"XdpCs/go-code-comment-standard","owner":"XdpCs","description":"Golang' code comment standard Go语言注释规范","archived":false,"fork":false,"pushed_at":"2023-04-03T05:28:51.000Z","size":271,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T17:19:01.692Z","etag":null,"topics":["comment","go","golang"],"latest_commit_sha":null,"homepage":"https://xdpcs.github.io/blogs/go/go_code_comment_standard/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XdpCs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-11T11:41:29.000Z","updated_at":"2024-04-27T12:03:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"d3440e85-f1da-4750-b629-b90b9da49ffd","html_url":"https://github.com/XdpCs/go-code-comment-standard","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"9c73207571658822cbcdd6793a928fb349d11d73"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XdpCs%2Fgo-code-comment-standard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XdpCs%2Fgo-code-comment-standard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XdpCs%2Fgo-code-comment-standard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XdpCs%2Fgo-code-comment-standard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XdpCs","download_url":"https://codeload.github.com/XdpCs/go-code-comment-standard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245328245,"owners_count":20597390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comment","go","golang"],"created_at":"2024-10-07T01:03:16.339Z","updated_at":"2025-03-24T18:31:40.007Z","avatar_url":"https://github.com/XdpCs.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go-Code-Comment-Standard\n\n![GitHub watchers](https://img.shields.io/github/watchers/XdpCs/Go-Code-Comment-Standard?style=social)\n![GitHub stars](https://img.shields.io/github/stars/XdpCs/Go-Code-Comment-Standard?style=social)\n![GitHub forks](https://img.shields.io/github/forks/XdpCs/Go-Code-Comment-Standard?style=social)\n![GitHub last commit](https://img.shields.io/github/last-commit/XdpCs/Go-Code-Comment-Standard?style=flat-square)\n![GitHub repo size](https://img.shields.io/github/repo-size/XdpCs/Go-Code-Comment-Standard?style=flat-square)\n![GitHub license](https://img.shields.io/github/license/XdpCs/Go-Code-Comment-Standard?style=flat-square)\n\n## 背景\n\n* 当新接手他人的项目，我们很容易不知所措，不知道这个函数的作用是什么，即使有很好的命名规范，这种事情也会时常发生，甚至有时候几个月不碰这个项目，自己再看这个函数，也会有一种云里雾里的感觉\n* 如果拥有好的注释，方便我们自己以后维护，也方便后来的同事接手你的项目，不至于对你的代码说这写的是啥，像一坨💩\n\n## 注释规范\n\n* 注释语言看团队，我们团队习惯使用英文，所以都使用英文，只要整个团队统一一个注释语言即可\n* 全部使用单行注释,`//`后需要使用一个空格\n\n## 包注释\n\n* 包注释是对包的介绍\n* 每个包都至少有一个包注释，在同一个包下，任一一个源文件中注释即可\n* 放置在`package`之前，来简短描述这个包的功能\n\n```go\n// 包的功能介绍\npackage 包名称\n```\n\n### 文件注释\n\n* 每个文件都应有一个文件注释\n* 放置在`package`之后，需要包含文件名称，文件描述，文件作者及其时间，更新作者及其时间\n* 因为在公司正常开发流程中，可能合并分支的时候，只有自己部门的业务主管，有这个权限进行合并代码，如果去看git的日志，如果只看主分支，只会显示主管的id，很难很快落实到每个人上\n\n```go\npackage 包名称\n\n// @Title        文件名称\n// @Description  文件描述\n// @Create       创建作者 日期 时间\n// @Update       更新作者 日期 时间\n```\n\n### 结构体注释和接口注释\n\n* 每个结构体或接口都应有注释\n* 在结构体或接口定义上面，需要有一个对整个结构体或接口的简要介绍\n* 结构体或接口内的每个成员变量也需要有注释\n\n```go\n// User defines user login info\ntype User struct {\n    UserName string // user's name\n    Password string // user's password\n}\n\n// IUser defines user function\ntype IUser interface {\n    Login()  // user login into the system\n    Logout() // user logout the system\n}\n```\n\n### 函数和方法的注释\n\n* 每个函数或方法都应有注释\n* 需要包含函数或方法名称、函数或方法描述、函数或方法的创建作者及其创建时间、输入参数及其参数类型和解释、返回参数及其参数类型和解释\n* 在函数或方法定义上面，书写下面的注释\n\n\n```go\n// 函数或方法名称\n// @Description        函数或方法描述\n// @Create             作者 日期 时间\n// @Param              输入参数名 参数类型 解释\n// @Return             返回参数名 参数类型 解释\n```\n\n* 如果涉及到函数或方法的变更，需要写明修改作者、修改日期和时间、修改的功能描述\n\n```go\n// @Modified           作者 日期 时间\n// @Modify description 修改的功能描述\n```\n\n### 代码逻辑注释\n\n* 每个代码块都需要添加注释\n\n```go\n// This is my wife's birthday\nif birthday == 1118 {\n    ...\n}\n```\n\n## 配置\n\n* 本配置均采用`Goland` IDE\n\n### 包注释和文件注释配置\n\n#### Mac 使用\n\n* Goland-\u003eSettings-\u003eEditor-\u003eFile and Code Templates-\u003eGo File\n* 复制下面的模版，替换原先的模版\n\n```shell\n// \npackage ${GO_PACKAGE_NAME}\n\n// @Title        ${FILE_NAME}\n// @Description  \n// @Create       XdpCs ${YEAR}-${MONTH}-${DAY} ${TIME}\n// @Update       XdpCs ${YEAR}-${MONTH}-${DAY} ${TIME}\n```\n\n![](./static/image1.jpg)\n\n### 修改注释的快捷键配置\n\n#### Mac 使用\n\n* Goland-\u003eSettings-\u003eEditor-\u003eLive Templates\n* 复制下面的模版，替换原先的模版\n```go\n// @Modified           XdpCs $date$ $time$:00\n// @Modify description \n```\n![](./static/image2.jpg)\n\n* 点击Edit Variables...\n* 配置如下图所示\n\n![](./static/image3.jpg)\n\n* 配置完成后，点击Define，勾选Go\n\n![](./static/image4.jpg)\n\n* 使用只需要使用modify+回车即可\n\n### 结构体注释、接口注释、函数注释、方法注释\n\n#### 安装插件\n\n* [Goanno插件](https://github.com/loveinsky100/goanno)\n* 同时也可以使用`Goland`的`Marketplace`搜索进行安装\n* 配置插件注释格式，使用Tools-\u003e Goanno Settings\n\n#### 函数注释、方法注释\n\n* Normal Method 配置、Interface Method 配置\n\n```shell\n// ${function_name}\n// @Description ${todo}\n// @Create         XdpCs ${date} \n// @Param          ${param_name} ${param_type}\n// @Return          ${ret_name_type}\n```\n\n#### 结构体注释\n\n* Struct 配置\n\n```shell\n// ${struct_name} \n```\n\n#### 接口注释\n\n* Interface 配置\n\n```shell\n// ${interface_name}\n```\n\n#### 测试\n\n* 使用`control + command + /`进行测试\n\n## 示例\n\n[示例](demo/main.go)\n\n## License\n\nGo-Code-Comment-Standard is under the [MIT](LICENSE). Please refer to LICENSE for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdpcs%2Fgo-code-comment-standard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdpcs%2Fgo-code-comment-standard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdpcs%2Fgo-code-comment-standard/lists"}