Shell脚本规范

Shell脚本规范

Google 开源项目风格指南

Google 开源项目风格指南英文版

Google Shell脚本规范

背景

• 使用哪一种Shell

Bash是唯一被允许执行的shell脚本语言

• 文件扩展名

可执行文件应该没有扩展名（强烈建议）或者使用.sh扩展名。库文件必须使用.sh作为扩展名，而且应该是不可执行的。

当执行一个程序时，并不需要知道它是用什么语言编写的。而且shell脚本也不要求有扩展名。所以我们更喜欢可执行文件没有扩展名。

• SUID/SGID

SUID(Set User ID)和SGID(Set Group ID)在shell脚本中是被禁止的。

如果你需要较高权限的访问请使用 sudo 。

• STDOUT vs STDERR

所有的错误信息都应该被导向STDERR。

0 是标准输入（STDIN），1 是标准输出（STDOUT），2 是标准错误输出（STDERR）。

# 将stderr重定向到file
$ command 2>file
# 将stderr追加到file文件末尾
$ command 2>>file

# 将stdout和stderr合并重定向到file
$ command > file 2>&1

# 将stdout和stderr合并重定向到file
$ command >& file

• 注释

  1. 文件头

  每个文件的开头是其文件内容的描述。

  每个文件必须包含一个顶层注释，对其内容进行简要概述。版权声明和作者信息是可选的。
  2. 功能注释

  任何不是既明显又短的函数都必须被注释。任何库函数无论其长短和复杂性都必须被注释。

  其他人通过阅读注释（和帮助信息，如果有的话）就能够学会如何使用你的程序或库函数，而不需要阅读代码。
  所有的函数注释应该包含：
  a. 函数的描述
  b. 全局变量的使用和修改
  c. 使用的参数说明
  d. 返回值，而不是上一条命令运行后默认的退出状态
  example：

  #!/bin/bash
  #
  # Perform hot backups of Oracle databases.
  
  export PATH='/usr/xpg4/bin:/usr/bin:/opt/csw/bin:/opt/goog/bin'
  
  #######################################
  # Cleanup files from the backup dir
  # Globals:
  #   BACKUP_DIR
  #   ORACLE_SID
  # Arguments:
  #   None
  # Returns:
  #   None
  #######################################
  cleanup() {
    ...
  }
  

  3. 实现部分注释

  注释你代码中含有技巧、不明显、有趣的或者重要的部分。

  这部分遵循谷歌代码注释的通用做法。不要注释所有代码。如果有一个复杂的算法或者你正在做一些与众不同的，放一个简单的注释。
  4. TODO注释

  使用TODO注释临时的、短期解决方案的、或者足够好但不够完美的代码。

  TODOs应该包含全部大写的字符串TODO，接着是括号中你的用户名。冒号是可选的。最好在TODO条目之后加上 bug或者ticket 的序号。

  example:

  # TODO(mrmonkey): Handle the unlikely edge cases (bug ####)
  

• 格式

  1. 缩进

  缩进两个空格，没有制表符。

  在代码块之间请使用空行以提升可读性。缩进为两个空格。无论你做什么，请不要使用制表符。对于已有文件，保持已有的缩进格式。

  2. 行的长度和长字符串

  行的最大长度为80个字符。

  如果你必须写长度超过80个字符的字符串，如果可能的话，尽量使用here document或者嵌入的换行符。长度超过80个字符的文字串且不能被合理地分割，这是正常的。但强烈建议找到一个方法使其变短。

  here document???

  3. 管道

  如果一行容不下整个管道操作，那么请将整个管道操作分割成每行一个管段。

  否则，应该将整个管道操作分割成每行一个管段，管道操作的下一部分应该将管道符放在新行并且缩进2个空格。这适用于使用管道符’|’的合并命令链以及使用’||’和’&&’的逻辑运算链。

  # All fits on one line
  command1 | command2
  
  # Long commands
  command1 \
    | command2 \
    | command3 \
    | command4
  

  4. 循环

  请将 ; do , ; then 和 while , for , if 放在同一行。

  shell中的循环略有不同，但是我们遵循跟声明函数时的大括号相同的原则。也就是说;do，;then 应该和if/for/while放在同一行。else应该单独一行，结束语句应该单独一行并且跟开始语句锤子对齐。

  5. case语句

  通过2个空格缩进可选项。
  在同一行可选项的模式右圆括号之后和结束符 ;; 之前各需要一个空格。
  长可选项或者多命令可选项应该被拆分成多行，模式、操作和结束符 ;; 在不同的行。

  匹配表达式比 case 和 esac 缩进一级。多行操作要再缩进一级。一般情况下，不需要引用匹配表达式。模式表达式前面不应该出现左括号。避免使用 ;& 和 ;;& 符号。

  6. 变量扩展

  按优先级顺序：保持跟你所发现的一致；引用你的变量；推荐用 ${var} 而不是 $var ，详细解释如下。

  这些仅仅是指南，因为作为强制规定似乎饱受争议。

  以下按照优先顺序列出。
  a) 与现存代码中你所发现的保持一致。
  b) 引用变量参阅下面一节，引用。
  c) 除非绝对必要或者为了避免深深的困惑，否则不要用大括号将单个字符的shell特殊变量或定位变量括起来。推荐将其他所有变量用大括号括起来。

• 特性及错误

  1. 命令替换

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

  # This is preferred:
  var="$(command "$(command1)")"
  
  # This is not:
  var="`command \`command1\``"
  

  2. test，[和[[

  推荐使用 [[ … ]] ，而不是 [ , test , 和 /usr/bin/ [ 。

  因为在 [[ 和 ]] 之间不会有路径名称扩展或单词分割发生，所以使用 [[ … ]] 能够减少错误。而且 [[ … ]] 允许正则表达式匹配，而 [ … ] 不允许。

  3. 测试字符串

  使用 -z -n 进行判断字符串时候为空。zero； not zero；

  4. 文件名通配符扩展

  当进行文件名的通配符扩展时，请使用明确的路径。
  ./* 比 * 来的安全得多

  5. 管道导向while循环

  请使用过程替换或者for循环，而不是管道导向while循环。在while循环中被修改的变量是不能传递给父shell的，因为循环 命令是在一个子shell中运行的。

• 命名约定

  命名注意单词属性：名词 动词等，已经顺序，在整个代码中需保持一致

  1. 函数名

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

  2. 变量名

  如函数名

  3. 常量及环境变量名

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

  4. 源文件名

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

  5. 只读变量

  使用 readonly 或者 declare -r 来确保变量只读。

  6. 使用本地变量

  使用 local 声明特定功能的变量。声明和赋值应该在不同行。

  使用 local 来声明局部变量以确保其只在函数内部和子函数中可见。这避免了污染全局命名空间和不经意间设置可能具有函数之外重要性的变量。
  当赋值的值由命令替换提供时，声明和赋值必须分开。因为内建的 local 不会从命令替换中传递退出码。

  7. 函数位置

  将文件中所有的函数一起放在常量下面。不要在函数之间隐藏可执行代码。

• 调用命令

  1. 检查返回值

  非管道命令，使用$?

  Bash也有 PIPESTATUS 变量，允许检查从管道所有部分返回的代码。如果仅仅需要检查整个管道是成功还是失败，可以使用下面的方式：

  tar -cf - ./* | ( cd "${dir}" && tar -xf - )
  if [[ "${PIPESTATUS[0]}" -ne 0 || "${PIPESTATUS[1]}" -ne 0 ]]; then
    echo "Unable to tar files to ${dir}" >&2
  fi
  

  只要你运行任何其他命令， PIPESTATUS 将会被覆盖。如果你需要基于管道中发生的错误执行不同的操作，那么你需要在运行命令后立即将 PIPESTATUS 赋值给另一个变量（别忘了 [ 是一个会将 PIPESTATUS 擦除的命令）
  如下：

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