docker-backup/llmdoc/reference/coding-conventions.md

Bash 脚本编码约定

1. 脚本结构约定

1.1 基本骨架

• 必须以 #!/bin/bash 开头
• 使用 set -e 和 set -o pipefail 启用严格错误处理
• 按照以下顺序组织脚本：
  1. Shebang
  2. 文件描述注释
  3. 变量和常量定义
  4. 日志和颜色输出函数
  5. 主要功能函数
  6. 主函数（main()）
  7. 主函数调用

1.2 错误处理

• 使用 set -e 在任何命令执行失败时立即退出脚本
• 使用 set -o pipefail 确保管道命令链任何一个失败都返回失败状态
• 对于可能失败的操作，编写明确的错误检查和日志记录机制

2. 命名约定

2.1 变量命名

• 全局变量使用大写，单词间使用下划线分隔
  • 正确: SCRIPT_DIR, DEFAULT_INSTALL_DIR
• 局部变量使用小写，单词间使用下划线分隔
  • 正确: backup_type, temp_backup_dir

2.2 函数命名

• 使用小写，单词间使用下划线分隔
• 动词 + 名词的形式
  • 正确: install_dependencies(), check_root()
  • 错误: Dependencies(), rootCheck()

3. 日志记录约定

3.1 日志级别

• 使用以下日志级别函数：
  • log_info(): 普通信息
  • log_warn(): 警告信息
  • log_error(): 错误信息

3.2 日志输出

• 日志应包含时间戳
• 使用颜色区分不同日志级别
• 日志消息应简洁明了，描述当前操作或状态

4. 注释风格

4.1 文件头注释

• 使用 ###############################################################################
• 包含脚本名称和简要功能描述

4.2 函数注释

• 在函数定义前使用块注释
• 描述函数的目的和关键行为

4.3 行内注释

• 仅在代码复杂或不明显时使用
• 解释 "为什么" 而非 "做什么"

5. 参数和配置处理

5.1 参数解析

• 使用 case 语句处理命令行参数
• 提供帮助选项（-h, --help）
• 对无效参数给出明确错误提示

5.2 配置加载

• 使用配置文件（如 YAML）管理可配置参数
• 提供合理的默认值
• 在加载配置时进行有效性检查

6. 性能和安全最佳实践

6.1 依赖检查

• 在脚本开始检查所有必需的外部工具
• 为缺失的依赖提供明确的安装指导

6.2 权限管理

• 对于需要特权的脚本，明确检查 root 权限
• 谨慎处理文件和目录权限

7. 示例项目特定约定

本项目脚本特有的一些约定：

• 使用 BASH_SOURCE[0] 获取脚本所在目录
• 支持通过环境变量覆盖默认配置
• 使用 trap 注册清理函数