Noteref

Noteref帮助您维护代码库中注释的引用。这对于记录先决条件、后置条件、不变性以及其他不由您的工具强制执行的假设尤其有用。例如，您可能有一个这样的注释

# This method always returns a non-empty list. [note:wibble_nonempty]
def wibble(x)
  ...
end

在其他地方，假设您正在编写依赖该后置条件的代码。您可以通过引用该注释来使这一点明确

flobs = wibble(wobble)

return flobs[0] # This is safe due to [ref:wibble_nonempty].

Noteref确保此类引用始终有效。如果有人尝试删除或重命名注释（例如，因为他们想更改wibble的行为），Noteref将会报错

Noteref到底做了什么呢？它会递归地扫描一个目录并检查以下内容

1. 引用实际上指向注释。在没有更新指向它的引用的情况下，不能删除注释。
2. 注释标签是唯一的。关于引用的是哪个注释永远不会存在歧义。

注释的语法是[note:label]，引用的语法是[ref:label]。Noteref适用于任何编程语言，并且会尊重您的.gitignore文件以及其他常见的过滤器文件。建议将Noteref设置为自动化持续集成检查。Noteref运行速度快，不太可能成为您CI的瓶颈。

安装

如果您正在运行macOS或基于GNU的Linux x86-64 CPU，以下命令将安装Noteref到/usr/local/bin

curl -LSfs https://raw.githubusercontent.com/stepchowfun/noteref/master/install.sh | sudo sh

如果您想安装到其他位置，您可以从发布页面下载二进制文件并将其放在您的$PATH上的任何位置。如果您的平台没有可用的预构建二进制文件，您可以使用Cargo构建并安装它。

使用

使用Noteref最简单的方法是运行不带参数的noteref命令。它将扫描工作目录并检查上述两种条件。以下是支持的命令行选项

USAGE:
    noteref [FLAGS] [OPTIONS]

FLAGS:
    -h, --help               Prints help information
    -n, --list-notes         Lists all the notes
    -r, --list-references    Lists all the references
    -V, --version            Prints version information

OPTIONS:
    -p, --path <PATH>    Sets the path of the directory to scan

致谢

Noteref 的想法受到了 GHC 注释约定 的启发。GHC 是其规模中可维护性最高的代码库之一。有关 GHC 开发者如何管理该代码库的更多见解，请参阅 这篇文章。