Nine times out of ten, I ignore comments unless I'm stumped. In fact, I'm tempted to make emacs hide all comments unless I explicitly expand them.
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.
It's faster to read the comments than to both trace and digest the code, no matter how understandable it is.
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 disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that.
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.
I disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that.
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.
Why do you have such a bee in your bonnet about Smalltalk? Are we not allowed to discuss the pros and cons of various commenting styles in other programming languages without you stopping by to evangelize? People who brag about their "encyclopedic" knowledge are usually about as welcome as encyclopedia salesmen.
Your comments are very insightful. I know this because I try to read the whole comment before judging. Unfortunately, even in fairly intelligent audiences like HN, it is common for people to form judgements based primarily on first impressions. Someone who reads only the first sentence (or even the second sentence) of any of your comments in this thread will think that your are hostile and condescending, which is probably why people are fighting back instead of listening to the insight that you share later in each comment. Your comments will generate more interesting conversation, and are more likely to be truly heard and understood, if you are more careful with your early words.
Your comments are very insightful. I know this because I try to read the whole comment before judging. Unfortunately, even in fairly intelligent audiences like HN, it is common for people to form judgements based primarily on first impressions.
"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?
Sometimes that "Incorrect conclusion from careless partial reading" is actually "Incorrect conclusion from reading ambiguous text." You can argue everything you say is always crystal clear, but...well...I'll leave it at that.
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.
I'm not sure if you were referring to me here, but personally I did read the entire comment and found all of it hostile and condescending. I also find his insinuation that I haven't read his comments thoroughly enough hostile and condescending.
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.
Stating that someone has "incomplete experience" is hostile, as opposed to informative? The statement was meant to tweak natural curiosity. Apparently, I'm supposed to stroke everyone's ego so that they feel perfect, otherwise I'm called "hostile."
First off, I apologize if I offended you somehow. However, my points are still as valid as they were the first time I made them- except maybe I don't disagree with everything you said. I didn't realize you were saying you know one context in which a debugger makes more sense rather than every context. I thought you meant most which I view as a fallacy for many reasons. The first of which being you don't know every context. But enough of that, I understand what you meant.
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.
As you said, some debuggers are better than others. However, you may be surprised by how much better some debuggers are than others. If you have any interest in debuggers, and how awesome they can be, it is worth giving VisualWorks a try.
I'm not going to make any assertions about anyone's experience. If you would like to see the Smalltalk debugger in action without trying the environment, have a look at the videos here (each is in the 2-5 minute range):
I like the way some languages support in-code documentation. That way, if you're like Jason Baker and don't read most comments because of the low signal-to-noise ratio compared to straight code, you can generate the documentation and simply read that. You get the high-level overview.
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.
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.
His blog post is the #1 story on slashdot.org right now, so being bold beats experience:
Corporate coding standards aside, I dont think over commenting is really an issue. I see the opposite trend 10's of thousands of lines of Java with no comments at all. Instead the use of meaningful names. So I see 30 to 50 characters method names, some of which differ only by a couple of characters in the middle. What is this subtle difference? A couple of lines of description is not too much to ask. Another example is convoluted business logic in the middle of a jsp (!!!) where formatting is little help and meaningful variable names just dont cut it.
Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless.
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.
The vast majority of the time, I'm writing comments for myself so that when I'm looking back on this same piece of code tomorrow, next week, next year, next decade, I can get myself into the same frame of mind. A comment on code I'm working on today isn't very useful. A comment on code I haven't looked at in 5 months and won't look at again for another 5 months is a lot more valuable. Very shortly I have to delve into some of my own code that's almost a decade old -- I hope I commented it well.
Given the authors resume, he might simply not have enough of his own old code to get the usefulness of comments.
I do it for the exact same reason. I was asked to work on a project one time (small OS) and I was going to remake the core. The person had made it a couple months ago and had no idea what was what when I asked him about it. If he had just taken the time to write a comment here or there explaining some of the things, it would have been much easier than debugging the entire OS (which I had to do). The worst part was that he put in all of these extra "checks" and "lists" containing information each time programs would run (ect.) and they turned out to be completely useless and affected nothing.
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.
For those of you wondering where the link to my resume went, I've since removed it. I'm not saying that what wvenable is saying isn't reasonable. It's just that I'd rather be judged by whether my content is very good rather than by my resume.
Short version: comments must be maintained and take visual room, so don't comment if it's not needed. Making the code self-documenting is usually good, except if it makes the function a lot longer or slower.
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):
Clearly no-one looking at that on its own could tell what it does. What it in fact does is look up a variable, specifically a global one ("Glo") withch is an lvalue ("Lv"). And the parasmeter is the variable name as a Python string. A more self documenting name might be:
But if I gave all my methods and variables such long names, the code would look terribly verbose and be hard to follow. So instead I use a comment that says what the method does, and specifies the type of its parameters and return value:
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
"""
Your original function name is pretty terrible and your alternative is an artificially bad example. If Lvalue implies variable (and possibly variable implies lvalue) then both are not necessary in the name. Var will be universally understood but Glo and Lv would stump anyone not familiar with your personal shorthand. The word lookup is unnecessary. You can still get something quite self-documenting and not all that verbose or long:
Nobody says you need to go all Java and make your variable names stupidly long. But small measures towards readability can go a long way to making code self-documenting and easier to understand.
Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless.
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.
In case anyone is wondering the parent post is a duplicate post that I made by accident. (Wireless connection dropped me and when I reloaded the page it reposted.) Unfortunately I can not delete it because someone has voted on it, and I can't flag my own post apparently. Anyway, mods please delete the parent post.
Just a bit of a clarification, a lot of people here seem to be interpreting what I'm saying as meaning "comments == bad", which isn't the truth (see my last point in the blog post)!
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.
It's not just that people aren't reading your last section. We are. Well, I did anyway, and I didn't get the impression from other comments on this article that people are skipping it. It's that your blog post is written against a problem that doesn't exist. Very few codebases in this world even have enough comments, and fewer still have too many.
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.
I don't necessarily agree with you, but I at least understand your point. Are coders who comment rarer than coders who don't? Probably so. Are coders who don't comment out of ideology more common than people who do comment out of ideology? I don't think so.
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.
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.
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).
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.
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.