1. 清晰简洁
- 注释应该简洁明了，避免冗长。直接指出代码的作用或目的。过多的注释可能会分散注意力，反而降低代码的可读性。
2. 注释代码块
- 对于复杂的逻辑块或算法，在代码块的上方添加注释，简要说明该段代码的功能或实现思路。这样可以帮助读者快速理解代码的整体结构和意图。
3. 注释函数和方法
-
每个公共函数（即首字母大写的函数）都应该有一个描述其功能、参数和返回值的注释。使用文档注释格式（以
//开头），并遵循 Go 语言的标准注释规范。- 说明函数的主要功能。
- 列出所有参数及其类型和用途。
- 描述返回值及其类型。
- 可以提供示例调用。
4. 注释变量和常量
- 对于重要的变量和常量，在声明时添加注释，说明其用途或含义。特别是全局变量和常量，注释尤为重要。
5. 注释结构体
- 对于结构体的字段，在字段声明时添加注释，说明每个字段的用途。这有助于其他开发者理解和使用这些结构体。
6. 注释接口
- 对于接口，应在接口声明上方添加注释，说明接口的目的和预期行为。对每个方法也应有简要说明，帮助实现者了解需要实现的功能。
7. 注释错误处理
- 对于复杂的错误处理逻辑，在代码中添加注释，说明每种错误情况的处理方式。这有助于调试和维护代码。
8. 注释配置和常量
- 对于配置文件和常量，在定义时添加注释，说明其用途和可能的值。这对于配置管理和调试非常有用。
9. 避免不必要的注释
- 不要在显而易见的代码上添加注释，例如简单的赋值语句或简单的控制流语句。注释应该补充代码，而不是重复代码。
10. 保持注释的更新
- 当修改代码时，确保相应的注释也得到更新，以保持注释与代码的一致性。过时的注释可能会导致误解和错误。
11. 使用一致的格式
- 在整个项目中使用一致的注释格式和风格。这有助于保持代码的整洁和专业性。
12. 文档生成工具
- 利用 Go 语言的文档生成工具（如
godoc或go doc），确保注释符合这些工具的要求，以便生成高质量的文档。
13. 示例和测试
- 在注释中提供示例用法和测试代码，可以帮助其他开发者更好地理解和使用你的代码。
14. 特殊标记
- 使用特殊的标记（如
TODO、FIXME）来标记需要进一步处理或改进的地方。这有助于团队成员跟踪和管理任务。
package main
import (
// 导入项目中的handler包，用于处理HTTP请求
"github.com/Moonlight-Zhao/go-project-example/handler"
// 导入项目中的repository包，用于与数据库交互
"github.com/Moonlight-Zhao/go-project-example/repository"
// 导入项目中的util包，可能包含一些工具函数
"github.com/Moonlight-Zhao/go-project-example/util"
// 导入gin框架，用于快速开发web应用
"gopkg.in/gin-gonic/gin.v1"
// 导入os标准库，用于执行操作系统相关的操作
"os"
)
// main 是程序的入口点
func main() {
// 调用Init函数进行初始化操作，如果有错误则退出程序
if err := Init(); err != nil {
os.Exit(-1)
}
// 创建一个默认的gin路由器实例
r := gin.Default()
// 使用中间件记录请求日志
r.Use(gin.Logger())
// 定义一个GET路由，当访问/ping时返回pong消息
r.GET("/ping", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "pong",
})
})
// 定义一个GET路由，用于获取社区页面的信息
r.GET("/community/page/get/:id", func(c *gin.Context) {
// 获取URL路径参数中的id
topicId := c.Param("id")
// 调用handler中的QueryPageInfo方法查询信息
data := handler.QueryPageInfo(topicId)
// 将查询到的数据以JSON格式返回
c.JSON(200, data)
})
// 定义一个POST路由，用于发布社区帖子
r.POST("/community/post/do", func(c *gin.Context) {
// 从表单数据中获取用户ID、主题ID和内容
uid, _ := c.GetPostForm("uid")
topicId, _ := c.GetPostForm("topic_id")
content, _ := c.GetPostForm("content")
// 调用handler中的PublishPost方法发布帖子
data := handler.PublishPost(uid, topicId, content)
// 将发布结果以JSON格式返回
c.JSON(200, data)
})
// 启动HTTP服务，监听默认端口
err := r.Run()
if err != nil {
// 如果启动失败，则返回
return
}
}
// Init 函数负责项目的初始化工作，包括但不限于数据库连接和日志初始化
func Init() error {
// 初始化repository模块，通常涉及数据库连接等操作
if err := repository.Init(); err != nil {
return err
}
// 初始化util模块，如初始化日志系统等
if err := util.InitLogger(); err != nil {
return err
}
// 没有错误发生时返回nil
return nil
}
