4 ms·

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 Te

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.

abecedarius 15y ago
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.
- msbarnett 15y ago
  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.
  - abecedarius 15y ago
    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.)
  - cema 15y ago
    What is the expected behavior of, say, multiplex('Tom', 0) or multiplex(null, 2) ?
    - kragen 15y ago
      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?
      - cema 15y ago
        Backward compatibility could be one such factor. In any case, documenting edge conditions helps in code maintenance.
        kragen 15y ago
        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.
- kragen 15y ago
  Even the Agile Manifesto itself explicitly says that its signatories value comprehensive documentation. They just value working software even more.
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]

abecedarius 15y ago

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.

msbarnett 15y ago
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.
- abecedarius 15y ago
  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.)
- cema 15y ago
  What is the expected behavior of, say, multiplex('Tom', 0) or multiplex(null, 2) ?
  - kragen 15y ago
    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?
    - cema 15y ago
      Backward compatibility could be one such factor. In any case, documenting edge conditions helps in code maintenance.
      - kragen 15y ago
        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.
kragen 15y ago
Even the Agile Manifesto itself explicitly says that its signatories value comprehensive documentation. They just value working software even more.

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]