

Myths about code comments - j_baker
http://jasonmbaker.com/myths-about-code-comments

======
tentonova
_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.

~~~
vlad
_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:

[http://developers.slashdot.org/story/10/01/01/226232/Myths-A...](http://developers.slashdot.org/story/10/01/01/226232/Myths-
About-Code-Comments?art_pos=1)

~~~
vlad
I wasn't serious :)

------
russell
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.

------
NathanKP
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.

------
wvenable
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.

~~~
dbz
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.

------
ramchip
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.

------
cabalamat
> Code must always be "self documenting"

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:

    
    
       def variableLookupGlobalLvalue(self, variableName):
    

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
          """

~~~
wvenable
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:

    
    
        def getGlobalVar(self, varName):
        def getGlobalLvalue(self, varName):
        def varLookupGlobal(self, varName):
        def lookupGlobalLvalue(self, varName):
        def globalLvalue(self, varName):
        ...
        

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.

~~~
cabalamat
> If Lvalue implies variable

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;
    

Here, a and c[x] are lvalues. b and d.y are rvalues.

~~~
wvenable
Right, but in the context of your function an expression is not possible --
you are passing a variable name to a lookup function.

------
NathanKP
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.

~~~
NathanKP
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.

------
jrockway
Myths about blog posts:

Every time you see one bad example of something, you have to write a blog post
detailing the related "best practices".

------
j_baker
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.

~~~
houseabsolute
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.

~~~
j_baker
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.

~~~
tentonova
_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).

~~~
j_baker
You and I have different experiences then. I've seen people who comment
_everything and anything_. And I know I'm not the only person who has seen
this:

[http://steve-yegge.blogspot.com/2008/02/portrait-
of-n00b.htm...](http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html)

~~~
tentonova
And since it's Steve Yegge, it must be right?

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.

------
thras
Well-written comments are generally helpful. And the people who write well-
written comments generally understand the concept of brevity.

Badly-written comments are worse than no comments at all.

Badly-named variables and functions are worst than that even.

