Hacker News Reader

Comment by msbarnett | Hacker News Reader

Would any amount of written documentation or comment make foo(a,b,c,d) any less of a hopeless mystery in use?

Yes, a poorly written test for a horribly named function with impenetrable argument names make for a shitty experience for the api user, but is that really insightful? Hopelessly meaningless method names with impenetrable arguments would be just as shitty to use if they came with a page-and-a-half of prose.

And if the hypothetical idiot who wrote your hypothetical test-as-documentation is the same idiot who would instead by providing some other form of written documentation, why would you expect it to be any more clear?

View on HN

Thats not a documenting test though, thats good choice of names. You don't need tests to have a good choice of names. If I said:

    slope, yintercept = calculateLine(x1, y2, x2, y2)

You wouldn't be using the test as documentation at all. Those names are so goddamn good you don't even need documentation. You would just be using the interface, and basic maths knowledge. (Note: it doesn't actually do that, I just thought of that as something that fits the argument/output count)

That's not a particularly good choice of names, actually:

> slope, yintercept = calculateLine(x1, y2, x2, y2)

It is, in fact, a place where a test would be quite helpful. A test might have prevented the typo for the second argument to calculateLine().

>A test might have prevented the typo for the second argument to calculateLine().

If the compiler didn't puke on it in the definition, or if that was the line in the test it would just be a bug in the test. Of course that all depends on the time honored development tradition of running a hastily written online comment in production. As far as the assumption I'm knocking tests for their utility at testing, I'm not, I'm knocking their utility as documentation.

> As far as the assumption I'm knocking tests for their utility at testing, I'm not, I'm knocking their utility as documentation.

Except you're not doing that, either. You're knocking the utility of a poorly-written tests-as-documentation test versus the utility of some hypothetically better written documentation.

But if your developers are going to write such uninformative tests-as-documentation, there's no reason to believe their documentation-as-documentation would be any better, so all you're really doing is making the uncontroversial assertion that poorly written documentation sucks.

Making the more relevant and informative comparison of well-written documentation-as-documentation to well-written tests-as-documentation, the tests-as-documentation have the inescapable bonus of being incapable of falling out of sync with the code.

In my, and a lot of other people's, experience, textual documentation tends to become an outdated liability almost as soon as it is written.

Reply on news.ycombinator.com