←back to thread

Unit tests as documentation

(www.thecoder.cafe)
94 points thunderbong | 1 comments | 17 Oct 24 17:22 UTC | HN request time: 0s | source
Show context
rglover ◴[17 Oct 24 18:03 UTC] No.41872038[source]▶
Just write the docs. A simple template:

- What is it?

- What does it do?

- Why does it do that?

- What is the API?

- What does it return?

- What are some examples of proper, real world usage (that don't involve foo/bar but instead, real world inputs/outputs I'd likely see)?

replies(3): >>41872068 #>>41872141 #>>41873752 #
MathMonkeyMan ◴[17 Oct 24 18:13 UTC] No.41872141[source]▶
I was going to say that unit tests have the benefit of breaking when the truth changes.

But then I realized that a lot of what makes a set of tests good documentation is comments, and those rot, maybe worse than dedicated documentation.

Keeping documentation up to date is a hard problem that I haven't yet seen solved in my career.

replies(4): >>41872241 #>>41872394 #>>41872424 #>>41874894 #
1. starkparker ◴[17 Oct 24 23:34 UTC] No.41874894[source]▶
Not that this solves the hard problem, but there's a simonw post for that: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...

Including screenshots, which a lot of tech writing teams raise as a maintenance burden: https://simonwillison.net/2022/Oct/14/automating-screenshots...

Then there are tools like Doc Detective to inline tests in the docs, making them dependent on each other; if documented steps stop working, the test derived from them fails: https://doc-detective.com/