Comment by atoav
11 hours ago
Not sure about this, but I like it the way it is done in the Rust ecosystem.
In Rust, there are two types of comments. Regular ones (e.g. starting with //) and doc-comments (e.g. starting with ///). The latter will land in in the generated documentation when you run cargo doc.
And now the cool thing: If you have example code in these doc comments, e.g. to explain how a feature of your library can be used, that script will automatically become part of the tests per default. That means you are unlikey to forget to update these examples when your code changes and you can use them as tests at the same time by asserting something at the end (which also communicates the outcome to the reader).
Doctests are great aren't they?
IDK, they sound like they overflow the "maximum code" counter and land up straight in the literate programming land. I wonder how far you could go writing your whole program as doctests spliced between commentary.
Does your IDE handle syntax-highlighting and intellisense -type enhancements for these unit tests written as doc-comments?
Yeah, combining unit tests and written docs in various ways seems fine. My reading of the article was that the tests are the only documentation. Maybe that was not the intent but just a bad interpretation on my part.
Though some replies here seem to keep arguing for my interpretation, so it's not just me.
Combining is what TFA suggests. They even go as far as closing the article with:
> Note also that I’m not suggesting that unit tests should replace any form of documentation but rather that they should complement and enrich it.