←back to thread

Unit tests as documentation

(www.thecoder.cafe)
94 points thunderbong | 6 comments | 17 Oct 24 17:22 UTC | HN request time: 0.001s | source | bottom
Show context
lucianbr ◴[17 Oct 24 18:16 UTC] No.41872163[source]▶
One - unit tests explain nothing. They show what the output should be for a given input, but not why, or how you get there. I'm surprised by the nonchalant claim that "unit tests explain code". Am I missing something about the meaning of the english word "explain"?

Two - so any input value outside of those in unit tests is undocumented / unspecified behavior? A documentation can contain an explanation in words, like what relation should hold between the inputs and outputs in all cases. Unit tests by their nature can only enumerate a finite number of cases.

This seems like such an obviously not great idea...

replies(14): >>41872317 #>>41872378 #>>41872470 #>>41872545 #>>41872973 #>>41873690 #>>41873888 #>>41874566 #>>41874890 #>>41874910 #>>41875148 #>>41875681 #>>41875896 #>>41876058 #
1. atoav ◴[17 Oct 24 18:30 UTC] No.41872317[source]▶
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).

replies(3): >>41872703 #>>41872805 #>>41874298 #
2. lucianbr ◴[17 Oct 24 19:00 UTC] No.41872703[source]▶
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.

replies(1): >>41876048 #
3. chrisweekly ◴[17 Oct 24 19:11 UTC] No.41872805[source]▶
Does your IDE handle syntax-highlighting and intellisense -type enhancements for these unit tests written as doc-comments?
4. readline_prompt ◴[17 Oct 24 22:06 UTC] No.41874298[source]▶
Doctests are great aren't they?
replies(1): >>41874460 #
5. TeMPOraL ◴[17 Oct 24 22:29 UTC] No.41874460[source]▶
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.
6. the_af ◴[18 Oct 24 03:11 UTC] No.41876048[source]▶
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.