26 Mar, 2010, Runter wrote in the 1st comment:
Votes: 0
This is the discussion thread for commenting_code
26 Mar, 2010, Idealiad wrote in the 2nd comment:
Votes: 0
Quote
Documentation of code is vitally important for successful, ongoing projects, but comments are not documentation, and it has no place in source files. Comments, when applicable, are annotations. Their purpose is to clarify the code, not explain it. They are ancillary hints as to the function or reasoning behind a particular construct to which they are attached. They are not substitutes for understanding of the problem to be solved or knowledge of language being used.


Python's docstrings?

Literate programming?
26 Mar, 2010, David Haley wrote in the 3rd comment:
Votes: 0
I think that there is an interesting separation to be made between on the one hand high-level design documentation and examining the strategy or approach being taken, and on the other hand lower-level explanations, API documentation, etc. But to go from that to say that comments are merely ancillary hints seems a little extreme. Often, comments (esp. comments describing an API, like any form of docstring) are absolutely vital in describing an API's constraints and assumptions, or the types of the input and output.
26 Mar, 2010, quixadhal wrote in the 4th comment:
Votes: 0
Not to mention the fact that some languages (Perl, Ruby?) support embedding high level documentation sections along with lower level docstrings. I typically write a high level doc that's at least equivalent to a man page at the top of my code, and will often have ancillary files embedded at the bottom (such as SQL schemas).

It sounds like the quoted material comes from a textbook that predates such ideas entirely. Back in the days of Pascal and Fortran, I might have agreed. We'll leave COBOL out of this… *grin*
26 Mar, 2010, Tyche wrote in the 5th comment:
Votes: 0
I think he's critiquing my code.

# Add an event 
# first, unclasp bra, then push tits.
def add_event(from,to,kind,msg=nil)
@bra.unclasp do
@tits.push(Event.new(from,to,kind,msg))
end
end
26 Mar, 2010, Runter wrote in the 6th comment:
Votes: 0
Not trying to cause an uproar. :P

Just thought maybe some new developers might want some tips on the subject.

Of course, you guys are welcome to add to the article. :)
27 Mar, 2010, shasarak wrote in the 7th comment:
Votes: 0
Part of the coding standards at the software company I work for is that you should virtually neveruse comments in code.

This is, not surprisingly, short-hand for a somewhat more sophisticated concept. :smile: The idea is that code should be written in such a way that it is immediately obvious what it does just by looking at it. This requires a lot of different practices to be used at once (all of which make for well-constructed OO code anyway); things like sensible division of responsibility between classes, meaningful variable and method names, not cluttering up names with spurious type information, making a typical method no more than half a dozen lines long, almost never passing more than one parameter into a method, never use switch statements, etc. Basically, if a piece of code is difficult enough to read that it requires a comment for you to be able to understand what it does, that virtually always means the code needs refactoring.

The only time we use comments is when the code works in a way which couldn't make sense unless you are aware of some piece of obscure real-world information. So there might be a comment saying "Clearly in any half-way sane situation this value will be null, but because of the way customer X models process Y, it won't be in situation Z". That's necessary so that people don't look at it and think "surely that must be a mistake". Otherwise, we don't use them.
27 Mar, 2010, David Haley wrote in the 8th comment:
Votes: 0
I wonder how many necessarily complex data structures you work with, or how much math or other such processes your code has, if it is the case that the code is always so simple you can read and write it in just a few lines.

You also have cases where some logic is simply complicated even if it only fits in a few lines of code, and it's extremely useful to document why the formula is the way it is (for instance, with a short proof of correctness).

It seems slightly insulting/obnoxious to say that anything else is bad programming. :thinking:
27 Mar, 2010, shasarak wrote in the 9th comment:
Votes: 0
David Haley said:
I wonder how many necessarily complex data structures you work with, or how much math or other such processes your code has, if it is the case that the code is always so simple you can read and write it in just a few lines.

Any given function may well require hundreds or even thousands of lines of code to carry out, of course. The make you make it readable is to break it up into progressively smaller chunks, each of which is sufficiently well-encapsulated that the code one layer up doesn't need to know how it operates internally. The higher-level code therefore provides an easily-readable "executive summary" of what the code one level down is doing; and each method invoked one level down provides more detail about how that specific aspect of the process is conducted - detail which you don't need delve into unless it is immediately important.
27 Mar, 2010, David Haley wrote in the 10th comment:
Votes: 0
What you're arguing is basic common sense that any good programmer would not disagree with: that it makes sense to decompose a problem into simpler subproblems. What I object to is that you seem to be saying that this is always possible to the extent that you need never document APIs because the function's definition alone tells you everything you need to know. Perhaps I should start making noise about how you're abandoning the totality of the commenting principle despite many smart people over a long period of time thinking that it was a great idea etc.

Anyhow, if you're going to state that your APIs never need documentation, then, well, frankly I question how complex your tasks are in the first place. I gave several examples where I believe that documentation is critical: you didn't respond to them. I am left not knowing whether you think what I said is utter bollocks, or agree that there are some areas where commenting is indeed useful.

Perhaps another question for you might be to ask if you're ever written truly complex code – not in terms of lines of code, but in terms of complexity of the problem being solved (which indeed might be solvable in a mere 50 lines of code) and whether that code "speaks for itself". This is related to the point I made about some code being greatly assisted by an accompanying proof of correctness (or even a proof sketch).

Yet another example why API documentation is useful is that I might not want to go read your SmallTalk code despite being able to (or having to) interface with it. A simple, concise API documentation will tell me everything that I need to know about it.
28 Mar, 2010, Koron wrote in the 11th comment:
Votes: 0
I don't see the problem with using excessive comments. It's not like mud code bases take up a huge chunk of HDD space, and they're often distributed for free to anyone who would like to try administrating one. This ends up very often being people who do not know how to code, and those brainless comments are a lot easier to understand, making your code a more pleasant starting point for learning how real programs actually look beyond the "hello world" level. Are the comments unnecessary if you know what you're doing? Of course. Is there a problem with creating your code so that an idiot* is less likely to do something stupid with it and come crying to you about it in the future? I don't think so.

*I do not mean to imply that people who start muds are necessarily idiots, but those tend to be the ones that cause the biggest stir, so it is probably wise to take measures to address them wherever you can.
28 Mar, 2010, David Haley wrote in the 12th comment:
Votes: 0
Well, speaking with the background of somebody who works with people who aren't necessarily 'idiots', having comments can help understand what's going on even if you do generally know what you're doing…
28 Mar, 2010, Runter wrote in the 13th comment:
Votes: 0
Koron said:
I don't see the problem with using excessive comments. It's not like mud code bases take up a huge chunk of HDD space, and they're often distributed for free to anyone who would like to try administrating one. This ends up very often being people who do not know how to code, and those brainless comments are a lot easier to understand, making your code a more pleasant starting point for learning how real programs actually look beyond the "hello world" level. Are the comments unnecessary if you know what you're doing? Of course. Is there a problem with creating your code so that an idiot* is less likely to do something stupid with it and come crying to you about it in the future? I don't think so.

*I do not mean to imply that people who start muds are necessarily idiots, but those tend to be the ones that cause the biggest stir, so it is probably wise to take measures to address them wherever you can.


Excessive comments in the source can actually make it more difficult to read the code. I.e.
/* Function to call roar() after 3 calls to mew()
* each call produces 1 mew or 1 roar
* count is static and incremented each call
* When count is 3 we'll know it's time to Roar!
* Function is used in kitty.c.
*/
void mewroar()
{ /* body of void mewroar() */
static char count; /* count is automatically zero. char is 1 byte. It can hold numbers.
* 1 byte is better for this than 4 or 8 bytes.
*/
count++; /* add 1 to count.
* Could have used count = count + 1; Same thing.
*/
if (count == 3) /* if count is equal to three */
{
count = 0; /* reset the value of count for future calls. */
roar(); /* function roar() called one time! */
} /* End if statement for when count is 3 */
else /* if count was not equal to three */
{
mew(); /* function mew() called one time. */
}
} // End of void mewroar()


If you decided at some point to revise those few lines of code you'd have to change all of your clumsy comments in that example to reflect the changes.

Or you can just write it in a less confusing, (arguably not less newbie friendly way.)
/*  calls mew().    calls roar() instead on every 3rd call. */
void roar_on_3() {
static int count = 0;
if (++count == 3) {
count = 0;
roar();
}
else
mew();
}


And I know it's an extreme example, but I have seen this type of commenting before particularly in MUDs.
28 Mar, 2010, David Haley wrote in the 14th comment:
Votes: 0
I think it's pretty clear that you shouldn't comment your code if it's absolutely clear what's happening. For example, commenting "i++" with "increase i by one" is not really helpful and indeed distracting. But, for example, the comment that every three calls makes a roar instead of a mew can in fact be useful, especially when it is picked up by an automatic documentation generator (like epydoc, doxygen, javadoc, rdoc, etc.).
28 Mar, 2010, Runter wrote in the 15th comment:
Votes: 0
David Haley said:
I think it's pretty clear that you shouldn't comment your code if it's absolutely clear what's happening. For example, commenting "i++" with "increase i by one" is not really helpful and indeed distracting. But, for example, the comment that every three calls makes a roar instead of a mew can in fact be useful, especially when it is picked up by an automatic documentation generator (like epydoc, doxygen, javadoc, rdoc, etc.).


I agree. I was just responding to the idea that you should comment to make the language readable in English for someone who doesn't know enough to read the code otherwise. Presumably even simple language statements. After all, it may be clear to most programmers that i++ means increase by one. On the other hand, to someone who doesn't really know any languages that may seem completely foreign.
28 Mar, 2010, flumpy wrote in the 16th comment:
Votes: 0
For a while I also was of the opinion that code should "read well" and minimal comments were necessary. Until I started producing API's, as DH hints at. Anything that could be a useful indicator of what compiled/unviewable code might do (for example, when it exists in a library or jar) is essential.

As for inline code comments, I often comment odd looking/complex looking code, mainly as a reminder to myself. Sometime I have found other peoples strange/complex looking code, changed it, and introduced bugs. If I leave a comment after I've done something complicated, it acts as a reminder as to why I did it that way so I don't mess with it. Of course, unit tests pick this up too, but only after the fact.

My pet hate is people commenting ends of statement blocks, like in Runter's example :( Why? I mean, it's obvious the block has ended. Only a moron wouldn't realize.
28 Mar, 2010, David Haley wrote in the 17th comment:
Votes: 0
Runter said:
I was just responding to the idea that you should comment to make the language readable in English for someone who doesn't know enough to read the code otherwise. Presumably even simple language statements. After all, it may be clear to most programmers that i++ means increase by one. On the other hand, to someone who doesn't really know any languages that may seem completely foreign.

Ah. Well I agree: you don't want to be explaining the most basic operations. It's hard to draw the line though as to when a line stops being self-explanatory, in terms of what the language construct actually means (calling a function is another story). I tend to use gut instinct regarding which lines are unusual enough to warrant explanations.

flumpy said:
My pet hate is people commenting ends of statement blocks, like in Runter's example :( Why? I mean, it's obvious the block has ended. Only a moron wouldn't realize.

It can be useful, if you have a long enough block, to note which block ended so that you don't have to bounce around in the source file to find out. Of course, some would point out that the One True Way is to have your blocks be small enough that "bouncing around" is just glancing up your screen, but, well.



Another distinction I draw between code comments and API comments is that the latter are for users of the code whereas the former are for people looking at the internals. In languages with docstrings (Python, Ruby, Java, …) this happens naturally, as the API documentation is usually a separate HTML file generated from the source. People only see the internal comments if they go look at the source. Those comments might have reasoning regarding implementation decisions. (That's another reason why comments are useful: why did I implement this using a linked list rather than a vector? Because the expected use case is XYZ.)

To sum up that last point: comments can explain the why in addition to, and sometimes more importantly than, the what. Even if you understand the "obvious code", you won't necessarily understand why the code was written that way.
28 Mar, 2010, shasarak wrote in the 18th comment:
Votes: 0
David Haley said:
What you're arguing is basic common sense that any good programmer would not disagree with: that it makes sense to decompose a problem into simpler subproblems. What I object to is that you seem to be saying that this is always possible to the extent that you need never document APIs because the function's definition alone tells you everything you need to know. Perhaps I should start making noise about how you're abandoning the totality of the commenting principle despite many smart people over a long period of time thinking that it was a great idea etc.

Or perhaps, for once, you should concentrate on usefully advancing the discussion, rather than merely attempting to score points.

David Haley said:
Anyhow, if you're going to state that your APIs never need documentation, then, well, frankly I question how complex your tasks are in the first place.

Yeah. And that's not in the least arrogant, patronising or insulting.

David Haley said:
Perhaps another question for you might be to ask if you're ever written truly complex code – not in terms of lines of code, but in terms of complexity of the problem being solved (which indeed might be solvable in a mere 50 lines of code) and whether that code "speaks for itself".

And neither is that.

David Haley said:
Yet another example why API documentation is useful is that I might not want to go read your SmallTalk code despite being able to (or having to) interface with it. A simple, concise API documentation will tell me everything that I need to know about it.

One thing which may be worth pointing out is that I never even mentioned API documentation. That's a different issue. Certainly an API needs to be documented; but putting comments in the code is quite possibly not the right way to do that. Comments in the code generally describe how something works internally, rather than how to use it. To put it slightly more formally: when you document an API, what you document is the public interface. Code comments become useful when you want to delve inside an API and find out howit does what it does - they describe the private implementation details. If an API requires you to know its implementation details in order to use it properly, then that API has been written badly.
28 Mar, 2010, Idealiad wrote in the 19th comment:
Votes: 0
That raises the question of where you put the API documentation though. Isn't it simpler to include it with the source for which it describes the interface? If the source changes, the interface may change as well, and it seems like extra work to have to keep up with two sets of files without need.
28 Mar, 2010, flumpy wrote in the 20th comment:
Votes: 0
David Haley said:
flumpy said:
My pet hate is people commenting ends of statement blocks, like in Runter's example :( Why? I mean, it's obvious the block has ended. Only a moron wouldn't realize.

It can be useful, if you have a long enough block, to note which block ended so that you don't have to bounce around in the source file to find out. Of course, some would point out that the One True Way is to have your blocks be small enough that "bouncing around" is just glancing up your screen, but, well.


I don't understand what you mean, I am guessing you are just being snide again. However.

I feel (and note the word feel) that large blocks of unreadable code belong to the stone age. I still come across code like this, and I still b0rk when I see it. I thought I'd left that sort of crud behind when I finished with basic, but still people insist on doing it. I can, and will, refactor that kind of code and remove the stupid comments.

However, I guess your kind of code is different, and you perhaps like to revel in the complexity of it: each to their own. When I have 3 hours to find the bug thats just taken down our website, and some idiot thought it would be fun to write 300* if statements in one method and then thought it would actually make it clearer by commenting the end of the code block, I just want to take that coder outside and shoot them.

* I am of course using hyperbole here, but not much.
0.0/24