(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)?

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.

1. Ygg2 ◴[17 Oct 24 18:35 UTC] No.41872394[source]▶

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

Rust doctests. They unite documentation and unit test. Basically documentation that's never so out of sync its assert fail.

Unit tests as documentation