Hacker News Reader

Comment by RangerScience | Hacker News Reader

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.

View on HN

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

Code is not always meant to be run by strangers, if it's internal to a team. The interface for customers should be documented.

There are multiple problems with that:

1. The code uses internal interfaces, not meant to be used by users of the code.

2. The code might not use the high level public interfaces you are interested in. Those interfaces are meant to be used by users, and tested by tests.

Having said that reading the code itself is often fruitful. Not for example usages, but to just learn how the thing is implemented.

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?

Reply on news.ycombinator.com