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.
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)
>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.
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?
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:
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.