3 ms·

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 fa

by bxr 15y ago

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.

humbledrone 15y ago
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.
- bxr 15y ago
  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?
  - humbledrone 15y ago
    > 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.
    - deleted 15y ago
      [deleted]
  - deleted 15y ago
    [deleted]
msbarnett 15y ago
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?
- bxr 15y ago
  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)
  - humbledrone 15y ago
    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().
    - bxr 15y ago
      >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.

by bxr 15y ago

humbledrone 15y ago

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.

bxr 15y ago
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?
- humbledrone 15y ago
  > 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.
  - deleted 15y ago
    [deleted]
- deleted 15y ago
  [deleted]

msbarnett 15y ago

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?

bxr 15y ago
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)
- humbledrone 15y ago
  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().
  - bxr 15y ago
    >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.