Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits.
The other case is API docs for libraries and frameworks meant for external consumption.
The Most Important Code Isn't Code
11–20 of 83 posts
Re: The Most Important Code Isn't Code
#12While I mostly agree, breaking out a comment for every parameter tends to wordiness and to encourage you not to see and explain your purpose synoptically. Like, this:
> Perform an n-fold frobulation. > @param n the number of times to frobulate > @param x the x-coordinate of the center of frobulation > @param y the y-coordinate of the center of frobulation > @param z the z-coordinate of the center of frobulation
could be "Frobulate n times around the center (x,y,z)." (From http://stackoverflow.com/questions/499890/what-is-your-perso... )
So the example would go "Return text concatenated count times." I'd try rewriting the longer example from a diff message in the OP, except it didn't fit in its own snippet!
A wordy style makes writing and maintaining comments feel like a chore; feeling like a chore, it gets done less. People start finding reasons comments are bad, and taking them for the whole story.
Re: The Most Important Code Isn't Code
#13I 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. ;)
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.
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.
Re: The Most Important Code Isn't Code
#14Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits. The other case is API docs for libraries and frameworks meant for external consumption.
I actually comment even simple code because comments show up a different color in my editors. Comments for me are often an additional mnemonic trigger rather than necessarily a store of detailed information. It's like indenting or bolding text. It helps with "chunking" while skimming code.
Re: The Most Important Code Isn't Code
#15[deleted]
Re: The Most Important Code Isn't Code
#16Earlier quoted context omitted.
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.
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'
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.
Re: The Most Important Code Isn't Code
#17The documentation example for the multiplex() function seems like massive overkill to me. The most informative part of the documentation comment is the line that starts with "Duplicate some text..." So why not just name the function duplicate_text() and be done with it? The arguments could be documented similarly, by naming them "text" and "num_duplications". I don't think I'd need an 11 line comment to tell me what…
That was pulled from the TomDoc spec- it was designed to demonstrate TomDoc, not the code. Having an overly complicated implementation makes explaining the documentation side of things a bit more difficult. :)
But that is a good point you make :) Is it maybe not the documentation that matters so much but the semantics communicated through the code itself?
Documentation is important, its just how its done today that bothers me. I have been reading the book "Computational Semantics with Functional Programming" and it has been quite intriguing. I would highly recommend it.
Re: The Most Important Code Isn't Code
#18I 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. ;)
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.
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))
Re: The Most Important Code Isn't Code
#19Earlier quoted context omitted.
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.
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],…
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.
Re: The Most Important Code Isn't Code
#20Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits. The other case is API docs for libraries and frameworks meant for external consumption.
An experienced engineer told me the purpose of documenting is not to tell what the new few lines do, it is to explain something that does not look right, or something to be careful with.