Shell脚本模版注释总结

1. 脚本头部注释

#!/bin/bash
# 脚本名称: example.sh
# 版本: 1.0.0
# 作者: 你的名字
# 创建日期: 2023-11-15
# 最后修改: 2023-11-16
# 描述: 这个脚本用于演示Shell脚本的各种注释方式
# 使用方式: ./example.sh [参数]
# 依赖: 列出需要的命令或软件，如awk, sed等
# 许可证: MIT

2. 变量注释

# 全局配置变量
CONFIG_FILE="/etc/app/config.conf"  # 配置文件路径
MAX_RETRIES=3                      # 最大重试次数
DEBUG_MODE=false                  # 调试模式开关

# 临时变量(不需要导出的变量)
local_var="temp"  # 临时存储数据

3. 函数注释

# 函数: calculate_sum
# 描述: 计算两个数的和并返回结果
# 参数:
#   $1 - 第一个数字
#   $2 - 第二个数字
# 返回值: 两数之和
calculate_sum() {
    local num1=$1
    local num2=$2
    echo $((num1 + num2))
}

4. 代码块注释

# ----------------------------
# 初始化部分开始
# ----------------------------

# 检查配置文件是否存在
if [ ! -f "$CONFIG_FILE" ]; then
    # 如果不存在则创建默认配置
    create_default_config
fi

# ----------------------------
# 初始化部分结束
# ----------------------------

5. 行内注释

for file in *.log; do
    # 只处理非空文件
    [ -s "$file" ] || continue
    
    # 压缩日志文件
    gzip "$file"  # 使用gzip压缩
done

6. 调试/临时注释

# TODO: 需要添加错误处理逻辑
# FIXME: 这里的硬编码需要改为从配置读取
# DEBUG: 打印变量值用于调试
# echo "Value: $value"

7. 多行注释(使用: <<语法)

: <<'COMMENT'
这是一个多行注释的示例
可以跨越多行
不会被解释器执行
常用于临时禁用大段代码
COMMENT

8. 参数处理注释

# 处理命令行参数
while getopts ":a:bc" opt; do
    case $opt in
        a)  # 设置参数a的值
            arg_a="$OPTARG"
            ;;
        b)  # 启用b选项
            mode_b=true
            ;;
        c)  # 启用c选项
            mode_c=true
            ;;
        \?) # 无效选项处理
            echo "无效选项: -$OPTARG" >&2
            exit 1
            ;;
    esac
done

9. 返回值/退出码注释

# 退出码定义
# 0 - 成功
# 1 - 一般错误
# 2 - 参数错误
# 3 - 文件不存在
# 4 - 权限不足

if [ ! -w "$LOG_FILE" ]; then
    echo "错误: 没有写入日志文件的权限" >&2
    exit 4  # 权限不足
fi

10. 示例注释

# 示例1: 基本用法
# ./example.sh -a value -b

# 示例2: 启用所有选项
# ./example.sh -a test -b -c