3 ms·

Totally agree: tests are the living documentation of usage! And if the team is properly collaborating, they are linking issues and merge requests with commits,

Totally agree: tests are the living documentation of usage! And if the team is properly collaborating, they are linking issues and merge requests with commits, providing historical snapshots of the ever evolving context!

AlotOfReading 4y ago
I find tests to be terrible usage documentation. Better than nothing to be sure, but compare compiler tests to a tutorial or example code for learning a programming language. The former are usable, but often full of obscure edge cases, layers of abstract test infrastructure, and mocks. The same probably applies to the tests in your codebase as well. They're just not designed for pedagogy in the same way docs should be.
- rmnclmnt 4y ago
  If your talking about learning and pedagogy, that's an entire different subject. When you are working on obscure code, you are not learning how the programming language works at the same time (I hope not). If you do, split the problem in two: learn on one side and apply on the other one. And yes tests are not the best candidate to learn how to do stuff. The best candidates for this are out of band documents / media / training.
  - AlotOfReading 4y ago
    The language thing was simply an example of an interface where it's very clear what the difference between proper documentation and tests is. It's the same sort of problem, but a slightly different context.
- yellowapple 4y ago
  Ideally, your tutorial/example code should also be among the test cases.
- mihaigalos 4y ago
  > I find tests to be terrible usage documentation. Better than nothing to be sure, but compare compiler tests to a tutorial or example code for learning a programming language. For example, Rust has documentation which is executed as tests (doctests). That way, when the code changes, the docs change automatically. To your mocks counter-example: How exactly would you propose to do it otherwise? If you write down an example which works now, how would you guarantee it still works if i.e. you don't use mocks but a say, a real database, which you then change. You would be in the case of 3 green parallel lines which are red and intersect. In a powerpoint/doc you can write whatever you want. Doesn't actually need to be true.

AlotOfReading 4y ago

I find tests to be terrible usage documentation. Better than nothing to be sure, but compare compiler tests to a tutorial or example code for learning a programming language. The former are usable, but often full of obscure edge cases, layers of abstract test infrastructure, and mocks. The same probably applies to the tests in your codebase as well. They're just not designed for pedagogy in the same way docs should be.

rmnclmnt 4y ago
If your talking about learning and pedagogy, that's an entire different subject. When you are working on obscure code, you are not learning how the programming language works at the same time (I hope not). If you do, split the problem in two: learn on one side and apply on the other one. And yes tests are not the best candidate to learn how to do stuff. The best candidates for this are out of band documents / media / training.
- AlotOfReading 4y ago
  The language thing was simply an example of an interface where it's very clear what the difference between proper documentation and tests is. It's the same sort of problem, but a slightly different context.
yellowapple 4y ago
Ideally, your tutorial/example code should also be among the test cases.
mihaigalos 4y ago
> I find tests to be terrible usage documentation. Better than nothing to be sure, but compare compiler tests to a tutorial or example code for learning a programming language. For example, Rust has documentation which is executed as tests (doctests). That way, when the code changes, the docs change automatically. To your mocks counter-example: How exactly would you propose to do it otherwise? If you write down an example which works now, how would you guarantee it still works if i.e. you don't use mocks but a say, a real database, which you then change. You would be in the case of 3 green parallel lines which are red and intersect. In a powerpoint/doc you can write whatever you want. Doesn't actually need to be true.