Noteref

Noteref helps you make notes in your codebase and maintain references to them. This is particularly useful for documenting preconditions, postconditions, invariants, and other kinds of assumptions that aren't enforced by your tooling. For example, you might have a note like this:

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

Elsewhere, you might depend on that postcondition. You can make this clear by referencing the note:

list = wibble(wobble)

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

Noteref ensures such references stay up-to-date. Concretely, Noteref scans a directory recursively and checks the following:

1. References actually point to notes. A note cannot be deleted without updating the references that point to it.
2. Note labels are distinct. There is never any ambiguity about which note is being referenced.

The syntax is [note:label] for notes and [ref:label] for references. Noteref works with any programming language, and it respects your .gitignore file as well as other common filter files.

Usage

The easiest way to use Noteref is to run the noteref command with no arguments. It will scan the working directory and check the two conditions described above.

USAGE:
    noteref [FLAGS] [OPTIONS]

FLAGS:
    -h, --help          Prints help information
    -n, --list-notes    List all the notes.
    -r, --list-refs     List all the refs.
    -V, --version       Prints version information

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

It is highly recommended to set up Noteref as an automated continuous integration check. Noteref is fast and probably won't be the bottleneck in your CI.

Acknowledgements

The idea for Noteref was inspired by the GHC notes convention. GHC is one of the most maintainable codebases for its size. This article has more insights into how the GHC developers manage that codebase.