Skip to Content
Shell注释

注释

文件头

每个文件都应以其内容描述开头。

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

示例：

#!/bin/bash
#
# Perform hot backups of Oracle databases.

函数注释

任何不是既明显又简短的函数都必须有函数头注释。库中的任何函数无论长度或复杂度 都必须有函数头注释。

其他人应该能够通过阅读注释（以及自助信息，如果提供的话）来学习如何使用你的程序 或使用你库中的函数，而无需阅读代码。

所有函数头注释应使用以下内容描述预期的 API 行为：

  • 函数描述。
  • 全局变量(Globals)：列出使用和修改的全局变量。
  • 参数(Arguments)：接受的参数。
  • 输出(Outputs)：输出到 STDOUT 或 STDERR 的内容。
  • 返回值(Returns)：除最后一个运行命令的默认退出状态以外的返回值。

示例：

#######################################
# Cleanup files from the backup directory.
# Globals:
#   BACKUP_DIR
#   ORACLE_SID
# Arguments:
#   None
#######################################
function cleanup() {
  …
}
 
#######################################
# Get configuration directory.
# Globals:
#   SOMEDIR
# Arguments:
#   None
# Outputs:
#   Writes location to stdout
#######################################
function get_dir() {
  echo "${SOMEDIR}"
}
 
#######################################
# Delete a file in a sophisticated manner.
# Arguments:
#   File to delete, a path.
# Returns:
#   0 if thing was deleted, non-zero on error.
#######################################
function del_thing() {
  rm "$1"
}

实现注释

对代码中复杂的、不明显的、有趣的或重要的部分添加注释。

遵循 Google 通用的编码注释实践。不要注释所有内容。如果有复杂的算法或你做了一些 不寻常的事情，请添加一个简短的注释。

TODO 注释

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

这与 C++ 指南 中的约定一致。

TODO 应包含全大写的字符串 TODO，后跟对相关问题拥有最佳上下文的人的姓名、 电子邮件地址或其他标识符。主要目的是提供一致的 TODO 格式，以便按需搜索以获取 更多详细信息。TODO 不是被引用人会修复该问题的承诺。因此，当你创建 TODO 时， 给出的几乎总是你自己的名字。

示例：

# TODO(mrmonkey): Handle the unlikely edge cases (bug ####)
Last updated on
环境格式