←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 #
rglover ◴[17 Oct 24 18:22 UTC] No.41872241[source]▶
The only fix for that is discipline. You can't automate away quality. The best people/teams understand that and make good docs a feature requirement, not an afterthought.

My favorite example is Stripe. They've never skimped on docs and you can tell they've made it a core competency requirement for their team.

replies(3): >>41872339 #>>41872469 #>>41876506 #
1. MathMonkeyMan ◴[17 Oct 24 18:31 UTC] No.41872339[source]▶
I wonder if there's some conservation law for "concerted mental effort." As if by spending time and energy on the often exasperating task of keeping documentation relevant, you reduce the time and energy required to comprehend the system.

You're right, it is a matter of culture and discipline. It's much harder to maintain a consistent and legible theory of a software component than it is to wing it with your 1-2 other teammates. Naming things is hard, especially when the names and their meanings eventually change.