goaidb/design/coding_style_guide.md

GoAIDB 编码与代码风格指南

目标

制定统一的编码规范，确保代码质量、可读性和可维护性。

适用范围

适用于本项目所有Go语言代码的编写和维护。

通用原则

1. 保持代码简洁清晰
2. 写好注释，特别是业务逻辑复杂的部分
3. 遵循最小化接口原则
4. 异常处理要全面
5. 内存管理要谨慎

命名规范

包命名

• 使用小写
• 简短且具有描述性
• 不使用下划线

// 正确示例
datastorage
queryprocessor

// 错误示例
DataStorage // 不应该大写
very_long_package_name // 太长了

变量命名

• 使用驼峰式命名法（CamelCase）
• 名称应明确表达变量含义
• 局部变量可以简短些，但不得影响理解

// 正确示例
userName
connectionPool

// 错误示例
unm // 含义不明
cp // 含义不明

函数命名

• 动词+名词形式
• 保持一致性
• 清晰表达函数作用

// 正确示例
CalculateUserRank()
ProcessQueryRequest()

// 错误示例
UserRank() // 动作不明确
DoSomething() // 含义模糊

格式规范

缩进

• 使用4个空格缩进
• 不使用Tab

行长度

• 每行不超过80个字符
• 特殊情况(如长URL)例外

空格

• 运算符两侧加空格
• 逗号后加空格
• 冒号后加空格

// 正确示例
result := a + b
args := make([]string, 0, 10)

// 错误示例
result:=a+b
args:=make([]string,0,10)

括号

• 左括号不要独占一行
• 控制结构必须使用括号

// 正确示例
if condition {
    // do something
}

// 错误示例
if condition
{
    // do something
}

注释规范

文件头注释

每个源文件都应包含以下信息：

• 文件功能说明
• 创建日期
• 创建人
• 修改记录（如有）

/*
 * @file: server.go
 * @description: TCP服务器核心实现
 * @author: 开发者姓名
 * @date: 2023-06-01
 */

函数注释

• 所有导出函数必须添加注释
• 使用Godoc标准格式

// ProcessQuery 处理客户端查询请求
// 参数:
//   query - 查询语句
// 返回值:
//   Result - 查询结果
//   error - 错误信息
func ProcessQuery(query string) (Result, error) {
    // 函数实现
}

行内注释

• 解释复杂逻辑
• 标记待办事项

// TODO: 优化性能
// HACK: 临时解决方案
// FIXME: 需要修复的问题

错误处理

• 所有错误必须检查
• 提供有意义的错误信息
• 统一错误处理机制

// 正确示例
if err != nil {
    log.Errorf("查询处理失败: %v", err)
    return nil, fmt.Errorf("query processing failed: %w", err)
}

// 错误示例
if err != nil {
    return nil // 静默忽略错误
}

日志规范

日志级别使用

• Error：记录错误事件，使用log.Error()，适用于不可恢复的错误
• Warn：记录警告事件，使用log.Warn()，表示潜在问题但不会中断流程
• Info：记录重要流程事件，使用log.Info()，用于关键节点的状态报告
• Debug：记录调试信息，使用log.Debug()，用于开发阶段的问题追踪

日志格式

• 所有日志必须包含上下文信息（如模块名、操作对象）
• 错误日志必须包含错误详情
• 关键操作应包含操作结果状态

// 正确示例
log.Error("存储层更新失败", "error", err, "db", dbName)
log.Warn("查询条件未命中索引", "collection", collName)
log.Info("更新操作完成", "matched", matchedCount, "modified", modifiedCount)

// 错误示例
log.Debug("错误不应使用debug级别") // 错误类型日志应使用Error级别
log.Info("error", err) // 错误信息应使用Error级别并包含明确描述

测试规范

• 所有关键功能必须有单元测试
• 测试用例覆盖主要分支
• 测试文件以_test.go结尾

Git提交规范

• 提交信息清晰明了
• 推荐格式: [模块] 操作描述

[server] 修复连接池泄漏问题
[parser] 支持新的查询语法

其他建议

• 保持函数单一职责
• 控制函数长度不超过50行
• 使用设计模式提高扩展性
• 定期重构优化代码结构
• 使用静态分析工具检查代码