Hacker News Reader

Comment by humbledrone | Hacker News Reader

You mean to say that a test like the following wouldn't be better than the comment for multiplex()?

  unless multiplex('Tom', 4) == 'TomTomTomTom'
    raise TestError( 'multiplex() failed' )
  end

Not only does that test communicate the exact same thing as the documentation comment, it is guaranteed to be correct and not out-of-date (assuming it's run as part of a test suite), whereas the comment can easily be wrong.

View on HN

It doesn't communicate the same thing. It communicates one example, leaving the reader to guess how to generalize it. Examples are good, testing is good; and specs are good too. It's currently popular to valorize the first two at the expense of the third, but I think this was an overreaction to the older dogma.

If the general behavior of multiplex isn't clear to the api-user from the example:

    multiplex('Tom', 4) == 'TomTomTomTom'

I'd argue that's a failure of the api designer that no amount of documentation is going to make up for.

Examples are good, testing is good, executable, testable documentation is doubly good, and predictable, intuitive api interfaces are invaluable; everything else is a liability that is going to go stale.

Covering every case provides value that covering just one does not. Natural language communicates in a way code does not. The tradeoffs are a bigger topic than I feel like arguing about in this thread.

(I agree with all you said except the last clause.)

What is the expected behavior of, say,

  multiplex('Tom', 0)

  multiplex(null, 2)
?

Well, if the function was designed by me, then the completely obvious answers are '' and a NullPointerException. Anything else is bug-prone — if the first case does something different, then nearly every caller of the function will need to check to see if the count is zero, or it will get behavior for that case that is not correct for its purposes; and if the second case does something different, then the function is choosing to provide incorrect output instead of crashing.

Also, I would have called it something different.

However, over the years, I've learned that many things that are obvious to me are not, in fact, true. So, what are the arguments for any other possible behavior?

Backward compatibility could be one such factor.

In any case, documenting edge conditions helps in code maintenance.

Since I'm coming from Python, JS, and C, passing a null instead of a string doesn't seem like an "edge condition"; it's the same kind of error as passing an integer or Map instead of a string. Passing 0, I suppose, is an edge condition.

Even the Agile Manifesto itself explicitly says that its signatories value comprehensive documentation. They just value working software even more.

I had written a really long response here, drawing on my experience as a software tester.

I've deleted my post and have decided to argue my point in another fashion. Please enlighten me to the meaning foo(), here is the documentation:

    tests = [
       #Format: [InputA, InputB, InputC, InputD, Output1, Output2]
       [1, 2, 3, 4, 12,  -7 ],
       [2, 3, 4, 5, 27,  -14],
       [3, 4, 5, 6, 48,  -23],
       [4, 5, 6, 7, 75,  -34],
       [5, 6, 7, 8, 108, -47],
       [6, 7, 8, 9, 147, -62],
    ]

    for a, b, c, d, o1, o2 in tests:
        failUnlessEqual((o1, o2), foo(a, b, c, d))

Can you tell me what foo() does please? Its a ridiculously simple function. I work with tests like this quite often. It doesn't confuse me though, I like to put comments in my code and even the test code, but you don't need those.

Nope, I am not going to bother. Your function has a terrible name, and the names of the arguments are not available to me. Had you given it a good name, and listed its arguments, I bet that the test would be quite a nice example of how to use it.

But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment.

edit: You did kind of prove my point by asking for documentation outside of the test. If this "documentation" test isn't enough to find out whats really going on in my 1-line function, what makes you think a test and the best-chosen names in the world would give you any insight to a 2-line function?

> But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment.

Your words, not mine.

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?

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