Unit tests as documentation

For something like this:

  def get_examples(
    source: Path,
    minimum_size: float,
    maximum_size: float,
    total_size: float,
    seed: float = 123,
  ) -> Iterator[Path]:
      …

…it’s pretty obvious what those float arguments are for but the “source” is just a Path. Is there an example “source” I can look at to see what sort of thing I am supposed to pass there?

Well you could document that abstractly in the function (“your source must be a directory available via NFS to all devs as well as the build infra”) but you could also use the function in a test and describe it there, and let that be the “living documentation” of which the original author speaks.

Obviously if this is a top level function in some open source library with a readthedocs page then it’s good to actually document the function and have a test. If it’s just some internal thing though then doc-rot can be more harmful than no docs at all, so the best docs are therefore verified, living docs: the tests.

(…or make your source an enumeration type so you don’t even need the docs!)