Myths about code comments
jasonmbaker.com
jasonmbaker.com
Given that Jason Baker just got out of school and is espousing a bold "I'm too smart for X" opinion (where X is, in this case, code comments), I'm not too inclined to pay much heed.
Only write comments that aid in understanding. I tend to comment a lot, but that's because I like someone to be able to approach my code and immediately understand the purpose of a particular code block. It's faster to read the comments than to both trace and digest the code, no matter how understandable it is.
After over a decade writing software, I much prefer over-commented code to under-commented code. No, comments aren't free, but the alternative is worse. Too few comments make your code unapproachable to others -- and eventually, yourself.
For those that like lots of comments to fully understand the code, you can read the documentation at the same time as the code comments. It's really the best of both worlds.
Then you have incomplete experience with development environments. Debug/trace is so easy in VisualWorks Smalltalk, that a lot of people use it to comment by including example code snippets meant to be debugged. Yes, let me say it again: debugging is so easy you can use it to comment! For the right kind of situation, this can indeed be the best way to comment code. Sometimes no description is going to be as helpful as just seeing an example of it happen.
Does this apply to other environments? Not necessarily. In VisualWorks, it's usually no problem to spawn off multiple "hypothetical" debug sessions, with no consequence, even if you are already in the debugger. A lot of people also prefer to code in the debugger. If the cost of debugger use were different, then it would not be so.
I've worked with different development environments and even if my experience is incomplete, it is still experience and I know the usefulness of a debugger. I also know how useful it is to comment out lines of code which will help the reader understand the code's process (and my thought process). However, I disagree entirely that a debugger is better than a few well placed (or a lot of well placed) comments. Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code. No matter how "good" you are at using a debugger. Comments are gold when used appropriately, and we (the person you are responding to and I) are only referring to the good type of comments. Bad comments are as good as giant commented out sections of code that belong to another program.
Actually, you don't disagree with everything I said. I don't see how you can, unless you have an encyclopedic knowledge of Smalltalk systems. You apparently disagree with a more extreme misreading of it. You're likely using rules of thumb developed while working in other environments, which may not be as universal as you think.
A synopsis of what I actually said: I know of one context where sometimes debugging is easier than reading comments. What is it that you think I said which you disagree with?
Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code.
Sometimes even the underlying concept is hard to grok from a written description, but easier to see played out. Sometimes the concept can be more difficult than any part of the code. Also, if your debugger is friendly enough, digesting running, tweakable, explorable code can be considerably easier than a static reading.
No matter how "good" you are at using a debugger.
I have been teaching an intro class where some egghead Wall Street quant spontaneously exclaimed: "Oh my gosh, this debugger is MAGIC!" From the assumptions you carry around, it seems likely you just lack the same kind of experience. The order of magnitude is about the same as going to GDB from no debugger at all.
Now, what was your point again?
Yes. I suppose bragging is a matter of interpretation, but you were certainly questioning his experience. E.g. you said:
> From the assumptions you carry around, it seems likely you just lack the same kind of experience.
Implying that the OP held mistaken views on commenting due to his lack of experience with Smalltalk debuggers.
>Now, what was your point again?
I was really asking a question rather than making a point. (I would say something about reading comprehension, but ...)
Now perhaps I should make a point about "writing comprehension."
You are right in the respect that sometimes the underlying concept can't be understood clearly from comments -and your method could suffice. I didn't mean to imply that comments are always the best thing imaginable one can add to his code. That is far from true. However, in my years of coding I have found comments to be very helpful.
I have used plenty of debuggers and some are better than others; however, claiming I have a lack of experience is ridiculous. Especially claiming I have the experience of some egghead Wall Street ?quant?(I've never heard of that word). You do not know me, you have never seen my code, and you most certainly have never seen me use a debugger. I wouldn't be so quick with those assumptions yourself.
http://www.cincomsmalltalk.com/userblogs/cincom/blogView?con...
"First impression" now equals "Incorrect conclusion from careless partial reading?"
And people wonder why I so often complain about "poor reading comprehension" even on HN?
And if that careless partial reading comment is directed at me, which it is fair for me to assume so seeing as this conversation started from a retort to my comment, I didn't only read a piece of the post. Before I comment I read the entire post and sometimes (usually on forums) I break the post apart like you've done and respond to pieces at a time.
Anyways. I find it very amusing that you disregarded such high praise; however, it would have been odd not to do so seeing as the poster seemed to make the mistake you seem to dislike.
Although you are correct in saying that the comment was hostile and condescending. I'm sure the poster meant it to be as such for many possible reasons none of which I will try to guess.
I posit the "tone" comes from the reader.
His blog post is the #1 story on slashdot.org right now, so being bold beats experience:
http://developers.slashdot.org/story/10/01/01/226232/Myths-A...
In the end I'm not quite sure what points he was trying to get across, but I like to use comments to keep track of logic flow.
I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.
Given the authors resume, he might simply not have enough of his own old code to get the usefulness of comments.
Anyways. My point is that a comment here or there on projects would help immensely. Especially if you may drop a certain part of a project and not maintain it for a period of more than a few days. Not all code is self explanatory.
This is in practice very hard to achieve. One reason is that a fully self-documenting name of a functiom might be rather verbose. I'll give an example based on code I'm currently working on. It contained this method definition (in Python):
def varGloLv(self, varp):
def variableLookupGlobalLvalue(self, variableName):
def varGloLv(self, varp):
""" lookup a variable, that's global and an lvalue
@param varp [string] the variable name
@return [UBasicType] the value of the variable
""" def getGlobalVar(self, varName):
def getGlobalLvalue(self, varName):
def varLookupGlobal(self, varName):
def lookupGlobalLvalue(self, varName):
def globalLvalue(self, varName):
...
Lvalue implies something that goes on the left side of an assign statement. An lvalue needn't be a variable, it could be a whole expression, E.g.:
a := b;
c[x] := d.y;
In the end I'm not quite sure what point he was trying to get across, but I personally like to use comments to keep track of logic flow.
I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. This results in typically a comment for every ten to twenty lines of code, with an occasional extra comment if there is something strange that I need to specially document. This is fairly sparse to some new programmers, but verbose enough for me. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.
Every time you see one bad example of something, you have to write a blog post detailing the related "best practices".
Quite the opposite in fact. Comments are almost like bold or italics: used sparingly, they have a big impact. But if you overuse them, they lose their effect. The moral of the story: comment your code. Just remember that there is such thing as overdoing it.
When I consider this and read an article warning about over-commenting, it suggests a certain perspective that I believe is incorrect. That is what I and probably many of the other readers reacted against in this post. If you only meant this article as an academic exercise ("hypothetically, in a world where people write too many comments, I would give this advice to over-commenters"), you need to say so at the top. Otherwise it gives the impression that you believe there is an over-commenting problem, and that someone might actually need to read this blog post or benefit from the advice contained within. Such people are rare.
More often than not, if someone is under-commenting, it's probably just out of laziness. However, if someone is over-commenting (which is possible in my opinion), chances are that it's because they believe that what they are doing is correct. Personally, I think posts such as this would be better to programmers in the latter category. A similar post aimed at the lazy under commenter probably would have no effect simply because such a person has been told they need to comment more throughout their programming careers.
That said, it really wasn't my intent to tell people they shouldn't comment. Rather, I'm merely trying to get people to think more about the comments they make. And that's not a bad thing all things considered.
I've yet to work with anyone outside of an undergraduate class that over-commented their code.
It takes effort to over-comment code, and those that do are invariably writing both poor code and poor comments.
A much more prevalent malaise is that of developers with an unduly high opinion of their code's readability grossly under-commenting their code. This increases the long-term maintenance overhead and sometimes leads to forced rewrites by follow-up maintainers (which may be the author himself).
http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm...
His "over-commented" example is clearly extreme hyperbole.
His under-commented counter-example is extremely poorly commented code which fails to explain the "why", ensuring that nobody can make sense of the code path without actually stopping to read the entire expression and possibly the expressions to which it refers.
Badly-written comments are worse than no comments at all.
Badly-named variables and functions are worst than that even.