I'd rather see unit tests as documentation.
replyThe test can show intended use, show interesting corner cases, and I know it is up to date because it is constantly running and passing.
I think that is a huge underrated benefit of adding a lot more testing.
If I think a developer is going to ask a question of how something works, or about a corner case, isn't that deserving of a test, so they can just see proof of the answer to their question immediately rather than trying to re-derive it?
I think unit tests are documentation in the same way that a Dockerfile is... it's not. The tests don't paint the bigger picture, explain why, etc.
replyThat said, if you pitched me something like a Jupyter notebook style doc where tests validating the claims of the documentation were inline, I'd totally buy into that.
You know what, you are right on the money with that. I think if you expand to include functional/smoke/e2e tests, that covers pretty much everything documentation is supposed to be.
replyJust by running them you can measure if they are in or out of sync with the code (well, if they were written correctly).
LLMs are great at writing unit tests.
reply