xxxigcc/llmdoc/reference/coding-conventions.md

编码规范

Shell 脚本编码规范

基本规则

• 所有 shell 脚本必须以 #!/bin/sh 或 #!/bin/bash 开头
• 使用 shellcheck 进行代码质量检查
• 脚本文件名使用小写，单词间用连字符或下划线连接（如 install-deb.sh, build_deb.sh）

注释规范

• 脚本开头必须包含简要注释，说明脚本用途
• 复杂逻辑块需添加行内注释
• 注释使用中文或英文，保持一致性

变量和函数

• 变量名使用大写或小写，保持一致（如 PACKAGE_NAME 或 package_name）
• 局部变量使用 local 关键字
• 函数名使用小写，单词间用下划线连接（如 install_package）

错误处理

• 使用 set -e 确保脚本遇到错误立即退出（可选）
• 对关键操作添加错误检查和异常处理

配置文件规范

• 使用标准 JSON 格式
• 配置文件名使用 .json 扩展名
• 保持配置文件的可读性，使用合理的缩进

命名约定

• 目录名：小写，单词间用连字符（script-utils）
• 文件名：小写，单词间用下划线或连字符（install_script.sh, build-deb.sh）
• 常量：全大写，下划线分隔
• 变量：根据项目风格统一

文档编写规范

• 使用 Markdown 格式
• 文档标题使用 #、## 等级别
• 保持文档简洁，重点突出
• 包含必要的使用示例和说明

代码提交

• 提交信息简洁明了
• 使用简体中文描述修改内容
• 遵循项目的 Git 提交规范

注意： 本规范为指导性文件，项目实践中可能有所调整。