←back to thread

Unit tests as documentation

(www.thecoder.cafe)
94 points thunderbong | 4 comments | 17 Oct 24 17:22 UTC | HN request time: 0s | source
Show context
jaredcwhite ◴[17 Oct 24 18:43 UTC] No.41872507[source]▶
I very much disagree with this.

Good code can be documentation, both in the way it's written and structured and obviously in the form of comments.

Good tests simply verify what the author of the test believes the behavior of what is being tested should be. That's it. It's not documentation, it rarely "explains" anything, and any time someone eschews actually writing documentation in the form of good code hygiene and actual docs in favor of just writing tests causes the codebase to suffer.

replies(1): >>41874406 #
1. RangerScience ◴[17 Oct 24 22:22 UTC] No.41874406[source]▶
I disagree in a very specific and limited way: good tests show you how to use the code, which can be as simple as just “here’s some typical parameters for this function.”

In more complex situations, good tests also show you the environmental set up - for example, all the various odd database records the code needs or expects.

It’s not everything you’d want out of a doc, but it’s a chunk of it.

replies(2): >>41875127 #>>41875744 #
2. bluefirebrand ◴[18 Oct 24 00:11 UTC] No.41875127[source]▶
> good tests show you how to use the code

If you can't find examples of how to use the code in the code then why does the code even exist?

replies(1): >>41875986 #
3. invaderzirp ◴[18 Oct 24 02:01 UTC] No.41875744[source]▶
Erm, this is what docs are for. Like a man page, where it'll give you function signatures and return types and explain what those functions do. Unit tests are not that, and they shouldn't be that, because that's not their purpose.

New rule: if you write a function, you also have to write down what it does, and why. Deal?

4. esafak ◴[18 Oct 24 02:58 UTC] No.41875986[source]▶
Code is not always meant to be run by strangers, if it's internal to a team. The interface for customers should be documented.