I couldn't agree more. Writing documentation tells me more about my own code than any level of testing ever has.
Both are important of course. ;)
Both are important of course. ;)
unless multiplex('Tom', 4) == 'TomTomTomTom'
raise TestError( 'multiplex() failed' )
end
multiplex('Tom', 4) == 'TomTomTomTom'
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.
(I agree with all you said except the last clause.)
multiplex('Tom', 0) multiplex(null, 2)
?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?
In any case, documenting edge conditions helps in code maintenance.
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))
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?
slope, yintercept = calculateLine(x1, y2, x2, y2)
> 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().
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.
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.
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?
Your words, not mine.