2 ms·

For today, I would focus on literate testing. The linear unit test is a better bottle for narrative content than the non-linear code. In a similar line, I beli

For today, I would focus on literate testing. The linear unit test is a better bottle for narrative content than the non-linear code. In a similar line, I believe automatic documentation should be generated from tests, not the implementation. Then it's always up to date. Text has many forms. Poems with many kinds of metrics, prose with all kinds of tones. Some forms are atemporal, some get old. None of it is "wrong", just different bottles to convey different ideas to different audiences.

bluGill 2y ago
I disagree. The most important documentation is for people who don't want to read your code just use it. Thus API documentation is important. Tests sort of do that, but they get into the wrong details - I don't want to read through a dozen different edge conditions for the first argument before you get to what the second argument does...
- alganet 2y ago
  I said documentation generated from literate tests (this does not exist yet), not tests as the final documentation artifact. The result would be similar to API docs, but derived from a more authoritative resource (tests, not docblocks). > I don't want to read through a dozen different edge conditions Neither do I. You mean you want the happy path in a distinct scenario. That is a very common perception amongst both testers and documentation writers. Good test suites have the happy path distinct from the edge conditions as well as good docs.
  - bluGill 2y ago
    I don't think it is possible to usefully deliver what you want, but if you can do that I'm all for it. Just having the code in my documentation checked that it compiles (which often means assumptions because I shouldn't have to put in boilerplate)
    - alganet 2y ago
      Python doctests[1] scratch that idea, but in another angle. They are useful and popular. clitest[2] is more closely related to what I'm aiming for, and it's very useful, but hard to translate to non-shell paradigms. I am sure it can be done. [1]: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html [2]: https://github.com/aureliojargas/clitest https://github.com/aureliojargas/clitest

bluGill 2y ago

I disagree. The most important documentation is for people who don't want to read your code just use it. Thus API documentation is important. Tests sort of do that, but they get into the wrong details - I don't want to read through a dozen different edge conditions for the first argument before you get to what the second argument does...

alganet 2y ago
I said documentation generated from literate tests (this does not exist yet), not tests as the final documentation artifact. The result would be similar to API docs, but derived from a more authoritative resource (tests, not docblocks). > I don't want to read through a dozen different edge conditions Neither do I. You mean you want the happy path in a distinct scenario. That is a very common perception amongst both testers and documentation writers. Good test suites have the happy path distinct from the edge conditions as well as good docs.
- bluGill 2y ago
  I don't think it is possible to usefully deliver what you want, but if you can do that I'm all for it. Just having the code in my documentation checked that it compiles (which often means assumptions because I shouldn't have to put in boilerplate)
  - alganet 2y ago
    Python doctests[1] scratch that idea, but in another angle. They are useful and popular. clitest[2] is more closely related to what I'm aiming for, and it's very useful, but hard to translate to non-shell paradigms. I am sure it can be done. [1]: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html [2]: https://github.com/aureliojargas/clitest https://github.com/aureliojargas/clitest