3 ms·

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 sur

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?

andoando 2y ago
I definitely do look at tests to see examples of how library is meant to be used. But thats quite different
sixthDot 2y ago
> 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 https://dlang.org/phobos/std_algorithm_searching.html#.all [1]: https://github.com/dlang/phobos/blob/master/std/algorithm/searching.d#L112-L156 https://github.com/dlang/phobos/blob/master/std/algorithm/se...
crabbone 2y ago
You are confused between "if" and "if and only if": "Tests are documentation" doesn't imply "documentation is tests". There are many useful tools that are documentation, none of them has to be exclusive.
actinium226 2y ago
As an example, when I was doing some complex stuff in pybind11 using callbacks, I heavily relied on their tests to understand how it was supposed to be implemented.

andoando 2y ago

I definitely do look at tests to see examples of how library is meant to be used. But thats quite different

sixthDot 2y ago

> 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 https://dlang.org/phobos/std_algorithm_searching.html#.all [1]: https://github.com/dlang/phobos/blob/master/std/algorithm/searching.d#L112-L156 https://github.com/dlang/phobos/blob/master/std/algorithm/se...

crabbone 2y ago

You are confused between "if" and "if and only if": "Tests are documentation" doesn't imply "documentation is tests". There are many useful tools that are documentation, none of them has to be exclusive.

actinium226 2y ago

As an example, when I was doing some complex stuff in pybind11 using callbacks, I heavily relied on their tests to understand how it was supposed to be implemented.