4 ms·

I see tests as documentation. They show you how to interact with a component and what the expected behavior should be. In BDD, you go one step further and write

I see tests as documentation. They show you how to interact with a component and what the expected behavior should be. In BDD, you go one step further and write down a formal description of inputs and expected outputs. Would agree that the higher level documentation (diagrams, process interaction, etc.) can be written down once the dust settles.

rmnclmnt 4y ago
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.
drewcoo 4y ago
This. Yes! Tests are documentation. And sometimes documentation and tests are called specs. Naming is hard. So is documentation. I did that just to trigger fallacy trolls, but sometimes smart naming is documentation. Maybe that hard work of naming is worth it. Verifying that code flow makes sense via code review guarantees that code is documented well enough. As does handing it to the intern, without any "training," and asking for a new feature. Or an expert in a different part of the stack but not this code. As does playing "spot the bug" and having most people understand the code, even if they don't see the bug. Heck, just passing through some linters and style analyzers can get you pretty close to not needing documentation. There are many things that count in different ways. What does your team want/need/desire? Does the answer change when it's someone else's code and their own? The flip side is a lot of prose in the human lingua franca wherever you code. (Probably American English but that's another screed.) That means people with coding chops also need literary chops. Or a friend who has them. It means that you're not only judged on how well you solve problems with code, not only with how easy that code is to inherently understand, but also judged on how well you can explain to someone else what it is and how to use it. If you really need that heavy documentation, hire a tech writer. Just like you probably specialize in a kind of dev, you can find specialists who specialize in making things make sense to devs. (I often recommend diagrams just to make boundaries clear to everyone "at a glance" but don't think those really count as documentation in this context.)

rmnclmnt 4y ago

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.

drewcoo 4y ago

This. Yes! Tests are documentation. And sometimes documentation and tests are called specs. Naming is hard. So is documentation. I did that just to trigger fallacy trolls, but sometimes smart naming is documentation. Maybe that hard work of naming is worth it. Verifying that code flow makes sense via code review guarantees that code is documented well enough. As does handing it to the intern, without any "training," and asking for a new feature. Or an expert in a different part of the stack but not this code. As does playing "spot the bug" and having most people understand the code, even if they don't see the bug. Heck, just passing through some linters and style analyzers can get you pretty close to not needing documentation. There are many things that count in different ways. What does your team want/need/desire? Does the answer change when it's someone else's code and their own? The flip side is a lot of prose in the human lingua franca wherever you code. (Probably American English but that's another screed.) That means people with coding chops also need literary chops. Or a friend who has them. It means that you're not only judged on how well you solve problems with code, not only with how easy that code is to inherently understand, but also judged on how well you can explain to someone else what it is and how to use it. If you really need that heavy documentation, hire a tech writer. Just like you probably specialize in a kind of dev, you can find specialists who specialize in making things make sense to devs. (I often recommend diagrams just to make boundaries clear to everyone "at a glance" but don't think those really count as documentation in this context.)