

My Case Against Code Comments - baumgartn3r
http://www.jakusys.de/blog/2010/12/my-case-against-code-comments/

======
ekidd
I think everybody hates comments like "getFoo: Get the value of Foo", and huge
blocks of commented-out code.

However, I _love_ seeing the following types of comments:

1\. The high-level overview of how things fit together: _This class represents
a compiled method at the VM level. It does not contain the actual native code.
If native code exists, it is handled using class Blah instead._

2\. What should work, but doesn't: _You'd think the following two lines of
commented-out code would work, but they don't, because libfoo 1.7.1 and
earlier has a stupid bug, so we need to do things the hard way._

3\. The epic warning: _Apple's Component Manager API does not work the way
you'd naturally assume. First of all, it constructs a single 'instance' of a
class before it initializes the class. Second, the memory reclamation system
is really weird..._ and so on, for a page and a half.

~~~
shaddi
Exactly. Code is for expressing how things are done.* Comments are for
expressing why.

* Or if you're not into the whole imperative languages bit, what things are done.

~~~
Mz
Totally OT: How are you managing to use an asterisk as a footnote indicator
and not ending up with the two asterisks invisible and the text in between in
italic? I've seen this before and I've tried to replicate it and I can't do
it. :-/

~~~
prodigal_erik
An asterisk followed by whitespace doesn't begin italics, so you get * word *
rather than _word_.

~~~
Mz
Oh. Thank you!

------
rgrove
Summary: "Bad comments are bad. Good comments are good."

------
mmaunder
Is the "Error establishing a database connection" on your site illustrative of
their mischief at work?

[I don't comment unless it's a TODO or a DONT EVER... ]

~~~
julian37
Google has a cached version:

[http://webcache.googleusercontent.com/search?q=cache:-cU7R0Q...](http://webcache.googleusercontent.com/search?q=cache:-cU7R0QdkYUJ:www.jakusys.de/blog/2010/12/my-
case-against-code-comments/&cd=1&hl=en&ct=clnk)

------
abecedarius
Nobody writes clearer code than Peter Norvig, yet he usually gives everything
a line-or-so doc comment -- e.g. <http://norvig.com/lispy2.html>. That's
pretty far from the comments-should-be- _rare_ credo. I like it.

My actual argument for that style sans appeals to authority:
[http://stackoverflow.com/questions/499890/what-is-your-
perso...](http://stackoverflow.com/questions/499890/what-is-your-personal-
approach-take-on-commenting/500268#500268)

~~~
knieveltech
Worthy of a standalone post somewhere so I can add it to my bookmarks. :)

~~~
abecedarius
Thanks -- maybe I'll get to it soon.

------
dwc
It's nice to see that yet one more person has come to their senses. Not much
new in that post, but sometimes that's ok.

The code itself is _always_ the first, best, and final authority on how it
works. Comments should add something beyond that, or they should not be there
at all. The __Thou Shalt Comment __mindset is responsible for most bad
comments. Ignore it and only comment when it will do the reader a service.

~~~
knieveltech
In theory everything you've said is accurate. In practice it's usually really
hard (if not impossible) to know exactly who "the reader" will be in six
months. Nothing says "prima dona" to me quite like encountering a few thousand
lines of someone else's code that they couldn't even be bothered to document
the major functions.

~~~
dwc
I comment for "me in six months" and that works ok. Not perfect, but ok.
Nothing says "unthinking clod" to me like a few thousand lines of code with
comments where I'm told that _i_ is a loop index.

~~~
knieveltech
I don't think anyone is advocating for comments explaining that $i is a loop
index.

~~~
dwc
I don't think so either. But that's what comes out of Thou Shalt Comment. And
yes, I _have_ seen loop index comments. Haven't you?

I think we'd both agree if we saw a good comment. I just want to focus on the
'good' part rather than the 'comment' part.

~~~
knieveltech
Of course I've seen loop index comments, and redundant variable declaration
comments, and all manner of bad commenting. Thing is, I'll take a bad comment
over blank code any day.

Crap comments warn me ahead of time that I'm dealing with a developer who's
either too inexperienced to know how to comment well or too sloppy to do a
good job at it and in either case I need to be paying closer attention to
their code than I might otherwise.

------
Groxx
Commented out code: frequently due to lack of version control, in my
experience. Or one-off tests that should've been removed, but they forgot.

    
    
      /** Class FooBar - The purpose of this class is to do XYZ... */
      public class FooBar { ... }
    

> _This is one of my favorite examples. Almost an entire line of comments
> wasted_

Not if you use a documentation-builder. They frequently result in simple
documentation turning into several lines (@param desc \n @param desc, and the
like). /* * does xyz * / _does not imply_ it is documenting that class and
only that class. It could easily be meant for two or three classes in the same
file, as they could be part of a greater whole.

------
bbuffone
I am currently getting a "Error establishing a database connection" for the
page. I hope where ever that happens; there might be a comment in the code
explaining why.

