Noteref helps you maintain references to notes in your codebase. 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:
```ruby
def wibble(x) ... end ```
Elsewhere, suppose you're writing some code that depends on that postcondition. You can make this clear by referencing the note:
```ruby flobs = wibble(wobble)
return flobs[0] # This is safe due to [ref:wibble_nonempty]. ```
Noteref ensures such references stay up-to-date. For example, if someone changes the behavior of wibble and deletes the note, Noteref will complain:
The poor stooge who wanted to change wibble will have to keep the note or update any code that references it. Then Noteref will be happy:
So what does Noteref do exactly? It recursively scans a directory and checks the following:
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. It is recommended to set up Noteref as an automated continuous integration check. Noteref is fast and probably won't be the bottleneck in your CI.
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. Here are the supported command-line options:
``` USAGE: noteref [FLAGS] [OPTIONS]
FLAGS: -h, --help Prints help information -n, --list-notes List all the notes. -r, --list-references List all the references. -V, --version Prints version information
OPTIONS:
-p, --path
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.