11 releases (breaking)
Uses old Rust 2015
0.9.1 | May 22, 2018 |
---|---|
0.8.1 | May 22, 2018 |
#13 in #maintain
195KB
535 lines
Noteref
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:
# This method always returns a non-empty list. [note:wibble_nonempty]
def wibble(x)
...
end
Elsewhere, suppose you're writing some code which depends on that postcondition. You can make this clear by referencing the note:
flobs = wibble(wobble)
return flobs[0] # This is safe due to [ref:wibble_nonempty].
Noteref ensures such references remain valid. If someone tries to delete or rename the note (e.g., because they want to change what wibble
does), Noteref will complain:
So what does Noteref do exactly? It recursively scans a directory and checks the following:
- References actually point to notes. A note cannot be deleted without updating the references that point to it.
- 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. It's recommended to set up Noteref as an automated continuous integration check. Noteref is fast and probably won't be the bottleneck in your CI.
Installation
If you are running macOS or a GNU-based Linux on an x86-64 CPU, the following will install Noteref to /usr/local/bin
:
curl -LSfs https://raw.githubusercontent.com/stepchowfun/noteref/master/install.sh | sudo sh
If you want to install to a different location, you can download a binary from the releases page and put it anywhere on your $PATH
. If there is no pre-built binary available for your platform, you can build and install it with Cargo.
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. Here are the supported command-line options:
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
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.
Dependencies
~4–14MB
~147K SLoC