4 ms·
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
by atoav 2y 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).
- lucianbr 2y agoYeah, 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.
- the_af 2y agoCombining 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.
- chrisweekly 2y agoDoes your IDE handle syntax-highlighting and intellisense -type enhancements for these unit tests written as doc-comments?
- bobbylarrybobby 2y agoYes, VSCode with rust-analyzer does
- chrisweekly 2y agoCool, thanks for the response. I don't understand the downvote for my question (shrug).
- readline_prompt 2y agoDoctests are great aren't they?
- TeMPOraL 2y agoIDK, 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.
- phi-go 2y agoDoctests are tests they are not part of a release build. Also I don't believe there is a supported way to access code in doctests from the outside. So (sadly?) no literate programming
- sedatk 2y agoI discovered that completely by surprise when I was learning Rust. I wrote code and unit tests, wrote some documentation, and I was blown away when I saw that my documentation also ran as part of the suite. Such a magical moment.