←back to thread

Unit tests as documentation

(www.thecoder.cafe)
174 points thunderbong | 1 comments | | HN request time: 0.212s | source
Show context
benrutter ◴[] No.41872611[source]
I've heard "tests are documentation" a lot, and even said it without thinkibg much myself. It sounds good, and I definitely like the idea of it, but I'm not sure it's true. Here's my thinking:

- I've never tried to understand a code base by looking at the tlunit tests first. They often require more in depth understanding (due to things like monkeypatching) than just reading the code. I haven't seen anyone else attempt this either.

- Good documentation is good as far as it aids understanding. This might be a side effect of tests, but I don't think it's their goal. A good test will catch breaks in behaviour, I'd never trade completeness for readability in tests, in docs it's the reverse.

So I think maybe, unit tests are just tests? They can be part of your documentation, but calling them documentation in and of themselves I think is maybe just a category error?

replies(4): >>41875780 #>>41877033 #>>41878206 #>>41879710 #
1. sixthDot ◴[] No.41877033[source]
> Good documentation is good as far as it aids understanding. This might be a side effect of tests, but I don't think it's their goal. A good test will catch breaks in behaviour, I'd never trade completeness for readability in tests, in docs it's the reverse.

The D language standard library uses both. When you generate the documentation from the comments attached to a declaration, the following unittests (they are identified using a special markup, (that is just triple slashes...) are also included.

Example once rendered [0], in the source you see the examples are actually unit tests [1].

[0]: https://dlang.org/phobos/std_algorithm_searching.html#.all

[1]: https://github.com/dlang/phobos/blob/master/std/algorithm/se...