Google 团队 Shell 编码风格指南-中文版

管道

如果管道不全都适合一行，则将其拆分为每行一个。

如果整个管道适合一行，则应在一行上。

如果不适合，则应在每行一个管道分段上拆分，换行处放置管道，并在下一个管道段的开头缩进2个空格。这适用于使用 | 组合的命令链，以及使用 || 和 && 的逻辑组合。

# 适合一行
command1 | command2

# 长命令
command1 
  | command2 
  | command3 
  | command4

循环

将 ; do 和 ; then 放在与 while、for 或 if 同一行。

在Shell中的循环与大括号的声明函数类似，因此在声明函数时遵循相同的原则。即 ; then 和 ; do 应与 if/for/while 放在同一行上。else 应单独一行，关闭语句应该单独一行，并与开放语句在垂直方向上对齐。

示例：

# 如果在函数内部，请考虑将循环变量声明为
# 本地变量，以避免其泄漏到全局环境中：
# local dir
for dir in "${dirs_to_cleanup[@]}"; do
  if [[ -d "${dir}/${ORACLE_SID}" ]]; then
    log_date "在 ${dir}/${ORACLE_SID} 中清理旧文件"
    rm "${dir}/${ORACLE_SID}/"*
    if (( $? != 0 )); then
      error_message
    fi
  else
    mkdir -p "${dir}/${ORACLE_SID}"
    if (( $? != 0 )); then
      error_message
    fi
  fi
done

Case语句

• 用2个空格缩进选项。
• 一行选项需要在模式的右括号之后和 ;; 之前加一个空格。
• 长或多命令选项应该拆分为多行，模式、操作和 ;; 放在单独的行上。

匹配表达式从 case 和 esac 缩进一个级别。多行操作再缩进一个级别。通常情况下，不需要引用匹配表达式。模式表达式不应该在开括号之前。避免使用 ;& 和 ;;& 符号。

case "${expression}" in
  a)
    variable="…"
    some_command "${variable}" "${other_expr}" …
    ;;
  absolute)
    actions="relative"
    another_command "${actions}" "${other_expr}" …
    ;;
  *)
    error "意外的表达式 '${expression}'"
    ;;
esac

对于简单的命令，可以将其放在与模式 和 ;; 相同的行上，只要表达式仍然可读。这通常适用于处理单个字母选项。当操作不适合单行时，将模式放在一行上，然后是操作，然后是单独的 ;; 也放在一行上。当与操作在同一行上时，在模式的右括号之后使用一个空格，在 ;; 之前再加一个空格。

verbose='false'
aflag=''
bflag=''
files=''
while getopts 'abf:v' flag; do
  case "${flag}" in
    a) aflag='true' ;;
    b) bflag='true' ;;
    f) files="${OPTARG}" ;;
    v) verbose='true' ;;
    *) error "意外的选项 ${flag}" ;;
  esac
done

变量扩展

按优先级顺序：保持与现有代码一致；对变量加引号；优先使用 "${var}" 而不是 "$var"。

这些是强烈推荐的准则，但并非强制性规定。尽管如此，这并不意味着这只是一个建议，不是强制性的，所以不能轻视或忽视它。

它们按优先级顺序列出。

• 保持与现有代码的一致性。

• 引用变量，参见下面的引用。

• 不要使用花括号将单字符shell特殊符号/位置参数括起来，除非绝对必要或避免深度混淆。

优先使用花括号将所有其他变量括起来。

# 推荐的用例部分。

# 优选的风格，用于 'special' 变量：
echo "位置参数: $1" "$5" "$3"
echo "特殊变量: !=$!, -=$-, _=$_. ?=$?, #=$# *=$* @=$@ $=$$ …"

# 需要花括号的情况：
echo "许多参数: ${10}"

# 避免混淆的花括号用法：
# 输出为 "a0b0c0"
set -- a b c
echo "${1}0${2}0${3}0"

# 其他变量的首选风格：
echo "PATH=${PATH}, PWD=${PWD}, mine=${some_var}"
while read -r f; do
  echo "文件=${f}"
done < <(find /tmp)

# 不推荐的用例部分。

# 未引用的变量、未使用花括号的变量、花括号将单字符shell特殊变量括起来。
echo a=$avar "b=$bvar" "PID=${$}" "${1}"

# 混淆的用法：这会被展开为 "${1}0${2}0${3}0"，
# 而不是 "${10}${20}${30}
set -- a b c
echo "$10$20$30"

注意：在 ${var} 中使用花括号 不是 引用的一种形式。引号必须同时使用。

引用

• 总是引用包含变量、命令替换、空格或shell元字符的字符串，除非需要小心不带引号的扩展，或者是一个Shell内部整数（见下一点）。
• 使用数组来安全地引用列表元素，尤其是命令行标志。参见下面的数组。
• 可选地引用Shell内部、只读的特殊整数变量：$?、$#、$$、$!（man bash）。出于一致性考虑，更喜欢引用“命名”的内部整数变量，例如 PPID 等。
• 更喜欢引用是“单词”（而不是命令选项或路径名）的字符串。
• 绝不引用文字整数。
• 要注意在 [[ … ]] 中进行模式匹配的引用规则。参见下面的Test、[… ] 和 [[… ]] 部分。
• 使用 "$@"，除非有特定原因使用 $*，例如在消息或日志中简单地附加参数。

# '单引号' 表示不需要替换。
# "双引号" 表示需要替换。

# 简单的例子

# "引用命令替换"
# 请注意，在 "$()" 中嵌套的引号无需转义。
flag="$(some_command and its args "$@" 'quoted separately')"

# "引用变量"
echo "${flag}"

# 使用数组与引用扩展以安全引用元素列表。
declare -a FLAGS
FLAGS=( --foo --bar='baz' )
readonly FLAGS
mybinary "${FLAGS[@]}"

# 对内部整数变量不需要引用，这是可以的。
if (( $# > 3 )); then
  echo "ppid=${PPID}"
fi

# "不引用文字整数"
value=32
# "引用命令替换"，即使您期望是整数
number="$(generate_number)"

# "优先引用单词"，不是必须的
readonly USE_INTEGER='true'

# "引用Shell元字符"
echo '你好，陌生人，很高兴认识你。赚很多 $$$'
echo "进程 $$：完成制作 $$$。"

# "命令选项或路径名"
# （假设 $1 在这里包含一个值）
grep -li Hugo /dev/null "$1"

# 较少简单例子
# "引用变量，除非明确为假"：ccs 可能为空
git send-email --to "${reviewers}" ${ccs:+"--cc" "${ccs}"}

# 位置参数的预防措施：$1 可能未设置
# 单引号保留正则表达式。
grep -cP '([Ss]pecial||?characters*)$' ${1:+"$1"}

# 对于传递参数，
# "$@" 几乎每次都是正确的选择，而
# $* 几乎每次都是错误的选择：
#
# * $* 和 $@ 会在空格上拆分，覆盖带有空格的参数
# 并丢弃空字符串；
# * "$@" 会保留参数，所以不提供参数将导致不传递参数；
#   这在大多数情况下是传递参数时想要使用的方式。
# * "$*" 扩展为一个参数，其中所有参数都由（通常）空格连接，
#   所以不提供参数将导致传递一个空字符串。
# （请查阅 `man bash` 以了解详细情况；- 注：指的是 `man bash` 中的相关内容）
(set -- 1 "2 two" "3 three tres"; echo $#; set -- "$*"; echo "$#, $@")
(set -- 1 "2 two" "3 three tres"; echo $#; set -- "$@"; echo "$#, $@")

特性和错误

ShellCheck

ShellCheck 项目 可以识别您的Shell脚本中的常见错误和警告。无论脚本是大是小，都建议使用它。

命令替换

使用 $(command) 而不是反引号。

嵌套的反引号需要用 转义内部的反引号。$(command) 格式在嵌套时不会改变，并且更容易阅读。

示例：

# 这是首选方式：
var="$(command "$(command1)")"
# 这不是：
var="`command `command1``"

测试，[ … ] 和 [[ … ]]

[[ … ]] 优于 [ … ]，test 和 /usr/bin/[。

[[ … ]] 减少了错误，因为在 [[ 和 ]] 之间不会发生路径名扩展或单词分割。此外，[[ … ]] 允许正则表达式匹配，而 [ … ] 不允许。

# 这确保左边的字符串由 alnum 字符类中的字符组成，后跟字符串 name。
# 请注意，RHS 在这里不应该被引用。
if [[ "filename" =~ ^[[:alnum:]]+name ]]; then
  echo "匹配"
fi

# 这匹配精确的模式 "f*"（在这种情况下不匹配）
if [[ "filename" == "f*" ]]; then
  echo "匹配"
fi
# 这会导致 "参数过多" 错误，因为 f* 被扩展为当前目录的内容
if [ "filename" == f* ]; then
  echo "匹配"
fi

要了解更多详细信息，请参阅 http://tiswww.case.edu/php/chet/bash/FAQ 中的 E14 部分。

测试字符串

在可能的情况下，请使用引号而不是填充字符。

Bash 足够聪明，可以处理测试中的空字符串。因此，鉴于代码更容易阅读，对空/非空字符串或空字符串使用测试，而不是填充字符。

# 使用这种方式：
if [[ "${my_var}" == "some_string" ]]; then
  do_something
fi

# -z（字符串长度为零）和 -n（字符串长度不为零）优于测试空字符串
if [[ -z "${my_var}" ]]; then
  do_something
fi

# 这是可以的（确保空边上的引号），但不是首选方式：
if [[ "${my_var}" == "" ]]; then
  do_something
fi
# 不要这样：
if [[ "${my_var}X" == "some_stringX" ]]; then
  do_something
fi

为避免对正在测试的内容产生困惑，明确地使用 -z 或 -n。

# 使用这个
if [[ -n "${my_var}" ]]; then
  do_something
fi
# 而不是这个
if [[ "${my_var}" ]]; then
  do_something
fi

为了清晰起见，对于相等性使用 == 而不是 =，尽管两者都可以工作。前者鼓励使用 [[]，而后者可能会与赋值混淆。然而，在 [[ … ]] 中使用 < 和 > 时要小心，它执行词典比较。对于数字比较，请使用 (( … )) 或 -lt 和 -gt。

# 使用这个
if [[ "${my_var}" == "val" ]]; then
  do_something
fi

if (( my_var > 3 )); then
  do_something
fi

if [[ "${my_var}" -gt 3 ]]; then
  do_something
fi
# 而不是这个
if [[ "${my_var}" = "val" ]]; then
  do_something
fi

# 可能意外的词典比较。
if [[ "${my_var}" > 3 ]]; then
  # 对于 4 为真，对于 22 为假。
  do_something
fi

文件名的通配符扩展

在进行文件名的通配符扩展时，请使用显式路径。

由于文件名可以以 - 开头，因此使用 ./* 而不是 * 扩展通配符更安全。

# 下面是目录的内容：
# -f  -r  somedir  somefile

# 错误地强制删除了目录中的几乎所有内容
psa@bilby$ rm -v *
removed directory: `somedir'
removed `somefile'
# 相反：
psa@bilby$ rm -v ./*
removed `./-f'
removed `./-r'
rm: cannot remove `./somedir': Is a directory
removed `./somefile'

Eval

应避免使用 eval。

eval 在用于变量赋值时会修改输入，并且可以设置变量而无法检查这些变量是什么。

# 这会设置什么？
# 它是否成功？部分或全部成功？
eval $(set_my_variables)

# 如果返回的值中有一个空格会发生什么？
variable="$(eval some_function)"

数组

应使用 Bash 数组来存储元素列表，以避免引号问题。这特别适用于参数列表。不应使用数组来实现更复杂的数据结构（请参见上面的何时使用Shell）。

数组存储有序的字符串集合，并且可以安全地扩展为命令或循环的单独元素。

应避免使用单个字符串作为多个命令参数，因为这最终会导致作者使用 eval 或尝试在字符串中嵌套引号，这不会产生可靠或可读的结果，而且会导致不必要的复杂性。

# 使用括号分配数组，可以使用 +=( … ) 追加。
declare -a flags
flags=(--foo --bar='baz')
flags+=(--greeting="Hello ${name}")
mybinary "${flags[@]}"
# 不要使用字符串表示序列。
flags='--foo --bar=baz'
flags+=' --greeting="Hello world"'  # 这不会按预期工作。
mybinary ${flags}
# 命令扩展返回单个字符串，而不是数组。避免在数组分配中使用未引用的扩展，因为如果命令输出包含特殊字符或空格，它将无法正常工作。

# 这将把列表输出扩展为字符串，然后执行特殊关键字扩展，然后进行空格分割。然后它才会变成一系列单词。ls 命令还可能根据用户的活动环境而改变行为！
declare -a files=($(ls /directory))

# get_arguments 将所有内容写入 STDOUT，然后经过上述的扩展过程，在变成一系列参数之前，经历了同样的过程。
mybinary $(get_arguments)

数组的优点

• 使用数组可以存储事物的列表，而不会引起混淆的引号语义。相反，不使用数组会导致试图在字符串中嵌套引号。
• 数组可以安全地存储任意字符串的序列/列表，包括包含空格的字符串。

数组的缺点

使用数组可能会增加脚本的复杂性。

数组的决策

应使用数组来安全地创建和传递列表。特别是在构建一组命令参数时，请使用数组来避免混淆的引号问题。使用带引号的扩展 – "${array[@]}" – 来访问数组。但是，如果需要更高级的数据操作，则应完全避免使用Shell脚本；请参见上面。

使用管道到While

首选使用进程替代或 readarray 内置命令（bash4+），而不是使用管道到 while。管道会创建一个子shell，因此在管道内部修改的任何变量不会传播到父shell。

管道到 while 中的隐式子shell可能会引入难以追踪的微妙错误。

last_line='NULL'
your_command | while read -r line; do
  if [[ -n "${line}" ]]; then
    last_line="${line}"
  fi
done

# 这将始终输出 'NULL'！
echo "${last_line}"

使用进程替代也会创建子shell。但是，它允许从子shell重定向到 while，而不需要将 while（或任何其他命令）放在子shell中。

last_line='NULL'
while read line; do
  if [[ -n "${line}" ]]; then
    last_line="${line}"
  fi
done < <(your_command)

# 这将输出 your_command 的最后一个非空行
echo "${last_line}"

或者，使用 readarray

内置命令将文件读入数组，然后循环遍历数组的内容。请注意（与上面的原因相同），必须使用进程替代来代替管道，但优势是输入生成的位置位于循环之前，而不是之后。

last_line='NULL'
readarray -t lines < <(your_command)
for line in "${lines[@]}"; do
  if [[ -n "${line}" ]]; then
    last_line="${line}"
  fi
done
echo "${last_line}"

注意：在遍历输出时使用 for 循环（例如 for var in $(...)）要小心，因为输出会按空格分割，而不是按行分割。有时您会知道这是安全的，因为输出不能包含任何意外的空格，但在这不明显或不会提高可读性的情况下（例如在 $(...) 内的长命令中），使用 while read 循环或 readarray 通常更安全和更清晰。

算术

始终使用 (( … )) 或 $(( … )) 而不要使用 let、$[ … ] 或 expr。

绝对不要使用 $[ … ] 语法、expr 命令或 let 内置命令。

< 和 > 在 [[ … ]] 表达式中不执行数值比较（它们执行的是词法比较；请参见测试字符串）。最好根本不要在数值比较中使用 [[ … ]]，而应使用 (( … ))。

建议避免将 (( … )) 用作独立的语句，同时要注意其表达式是否评估为零，尤其是在启用了 set -e 的情况下。例如，set -e; i=0; (( i++ )) 将导致 shell 退出。

# 用作文本的简单计算 - 注意在字符串内使用 $(( … ))。
echo "$(( 2 + 2 )) is 4"

# 在进行算术比较测试时
if (( a < b )); then
  …
fi

# 将一些计算结果赋给变量。
(( i = 10 * j + 400 ))
# 这种形式不可移植且已过时
i=$[2 * 10]

# 尽管外观上看，'let' 不是声明性关键字之一，
# 但未引用的赋值会受到单词分割的影响。
# 为了简化起见，避免使用 'let'，改用 (( … ))
let i="2 + 2"

# expr 实用程序是一个外部程序而不是 shell 内置命令。
i=$( expr 4 + 4 )

# 使用 expr 时引号可能会导致错误。
i=$( expr 4 '*' 4 )

尽管在风格上有考虑因素，但是 shell 的内置算术要比 expr 快得多。

在使用变量时，不需要在 $(( … )) 中使用 ${var}（和 $var）形式。Shell 会自动为您查找 var，省略 ${…} 可以使代码更加简洁。尽管这与之前关于始终使用花括号的规则稍有不同，但这仅仅是一些建议。

# 注意：在可能的情况下，请记得将变量声明为整数，并优先使用局部变量而不是全局变量。
local -i hundred=$(( 10 * 10 ))
declare -i five=$(( 10 / 2 ))

# 将变量 "i" 增加三个。
# 注意：
# - 我们不写 ${i} 或 $i。
# - 我们在 (( 前后加上空格。
(( i += 3 ))

# 要将变量 "i" 减少五个：
(( i -= 5 ))

# 进行一些复杂的计算。
# 请注意，正常的算术运算符优先级会被遵循。
hr=2
min=5
sec=30
echo $(( hr * 3600 + min * 60 + sec )) # 预期输出 7530

命名约定

函数名

小写，用下划线分隔单词。使用 :: 分隔库。函数名后必须加上括号。function 关键字是可选的，但在整个项目中必须保持一致使用。

如果你只是写单个函数，使用小写并用下划线分隔单词。如果你在写一个包，用 :: 分隔包名。大括号必须与函数名在同一行（与 Google 的其他语言一样），函数名与括号之间不要留空格。

# 单个函数
my_func() {
  …
}

# 包的一部分
mypackage::my_func() {
  …
}

当函数名后跟有“()”时，function 关键字是多余的，但它有助于快速识别函数。

变量名

与函数名相同。

循环中的变量名应与要循环的任何变量具有相似的命名。

for zone in "${zones[@]}"; do
  something_with "${zone}"
done

常量和环境变量名

全部大写，用下划线分隔，放在文件顶部声明。

常量和任何导出到环境的内容都应使用大写字母。

# 常量
readonly PATH_TO_FILES='/some/path'

# 同时是常量和环境变量
declare -xr ORACLE_SID='PROD'

有些内容在首次设置时变成常量（例如，通过 getopts）。因此，可以在 getopts 中或基于条件设置常量，但之后应立即将其设置为只读。出于清晰起见，建议使用 readonly 或 export，而不是等效的 declare 命令。

VERBOSE='false'
while getopts 'v' flag; do
  case "${flag}" in
    v) VERBOSE='true' ;;
  esac
done
readonly VERBOSE

源文件名

小写，如果需要，用下划线分隔单词。

为了与 Google 的其他代码风格保持一致，使用小写的文件名，并用下划线分隔单词，如 maketemplate 或 make_template，而不是 make-template。

只读变量

使用 readonly 或 declare -r 确保它们是只读的。

由于全局变量在 shell 中被广泛使用，因此在处理它们时捕获错误非常重要。当声明一个意味着只读的变量时，必须明确说明。

zip_version="$(dpkg --status zip | grep Version: | cut -d ' ' -f 2)"
if [[ -z "${zip_version}" ]]; then
  error_message
else
  readonly zip_version
fi

使用局部变量

使用 local 声明函数特定的变量。声明和赋值应位于不同的行。

在声明局部变量时使用 local，以确保局部变量只能在函数及其子函数中访问。这样可以避免污染全局命名空间，并无意中设置可能在函数外部具有意义的变量。

当赋值值由命令替换提供时，声明和赋值必须分开成两个语句，因为 local 内置命令不会传播命令替换的退出代码。

my_func2() {
  local name="$1"

  # 分开的声明和赋值行：
  local my_var
  my_var="$(my_func)"
  (( $? == 0 )) || return

  …
}
my_func2() {
  # 不要这样做：
  # $? 总是为零，因为它包含 'local' 的退出代码，而不是 my_func 的退出代码
  local my_var="$(my_func)"
  (( $? == 0 )) || return

  …
}

函数位置

将所有函数放在文件的常量下面。不要在函数之间隐藏可执行代码。这样做会使代码难以跟踪，并在调试时产生令人讨厌的意外。

如果你有多个函数，将它们全部放在文件顶部附近。只有包含、set 语句和设置常量可以在声明函数之前执行。

main

对于至少包含一个其他函数的较长脚本，需要一个名为 main 的函数。

为了方便找

到程序的起始点，将主要代码放在一个名为 main 的函数中，作为最底部的函数。这与代码库的其余部分保持一致，同时还允许您将更多变量定义为 local（如果主要代码不是函数，则无法实现此功能）。文件中的最后一行非注释行应调用 main：

main "$@"

当然，在只有线性流程的短脚本中，使用 main 是不必要的。

调用命令

检查返回值

始终检查返回值并给出有信息的返回值。

对于未使用管道的命令，使用 $? 或通过 if 语句直接检查，以保持简单。

示例：

if ! mv "${file_list[@]}" "${dest_dir}/"; then
  echo "无法将 ${file_list[*]} 移动到 ${dest_dir}" >&2
  exit 1
fi

# 或者
mv "${file_list[@]}" "${dest_dir}/"
if (( $? != 0 )); then
  echo "无法将 ${file_list[*]} 移动到 ${dest_dir}" >&2
  exit 1
fi

Bash 还有 PIPESTATUS 变量，允许检查管道的所有部分的返回代码。如果仅需要检查整个管道的成功或失败，那么以下内容是可以接受的：

tar -cf - ./* | ( cd "${dir}" && tar -xf - )
if (( PIPESTATUS[0] != 0 || PIPESTATUS[1] != 0 )); then
  echo "无法将文件打包到 ${dir}" >&2
fi

然而，由于一旦执行其他命令，PIPESTATUS 将被重写，如果需要根据管道中发生错误的位置采取不同的错误处理方式，你需要在运行命令后立即将 PIPESTATUS 赋值给另一个变量（不要忘记 [ 是一个命令，会清除 PIPESTATUS）。

tar -cf - ./* | ( cd "${DIR}" && tar -xf - )
return_codes=( "${PIPESTATUS[@]}" )
if (( return_codes[0] != 0 )); then
  do_something
fi
if (( return_codes[1] != 0 )); then
  do_something_else
fi

内置命令 vs. 外部命令

在选择调用内置命令和调用单独的进程之间，选择内置命令。

我们更喜欢使用内置命令，例如 bash(1) 中的 参数扩展 函数，因为它更健壮和可移植（特别是与像 sed 这样的东西相比）。

示例：

# 更喜欢这种写法：
addition=$(( X + Y ))
substitution="${string/#foo/bar}"
# 而不是这种写法：
addition="$(expr "${X}" + "${Y}")"
substitution="$(echo "${string}" | sed -e 's/^foo/bar/')"

结论

理性思考并保持一致性。

请花几分钟阅读 C++ Guide 底部的 Parting Words 部分。

修订版本 2.02