# 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` 注册清理函数