←back to thread

Unit tests as documentation

(www.thecoder.cafe)
94 points thunderbong | 1 comments | 17 Oct 24 17:22 UTC | HN request time: 0.447s | source
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. __MatrixMan__ ◴[17 Oct 24 18:41 UTC] No.41872470[source]▶
Often, tests are parameterized over lists of cases such that you can document the general case near the code and document the specific cases near each parameter. I've even seen test frameworks that consume an excel spreadsheet provided by product so that the test results are literally a function of the requirements.

Would we prefer better docs than some comments sprinkled in strategic places in test files? Yes. Is having them with the tests maybe the best we can do for a certain level of effort? Maybe.

If the alternative is an entirely standalone repository of docs which will probably not be up to date, I'll take the comments near the tests. (Although I don't think this approach lends itself to unit tests.)