[creativename]

I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does".

I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused.

To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.

[lawn]

> I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does".

There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example:

    '*************************************************
    ' Name: CopyString
    '
    ' Purpose: This routine copies a string from the source
    ' string (source) to the target string (target).
    '
    ' Algorithm: It gets the length of "source" and then copies each
    ' character, one at a time, into "target". It uses
    ' the loop index as an array index into both "source"
    ' and "target" and increments the loop/array index
    ' after each character is copied.
    '
    ' Inputs: input The string to be copied
    '
    ' Outputs: output The string to receive the copy of "input"
    '
    ' Interface Assumptions: None
    '
    ' Modification History: None
    '
    ' Author: Dwight K. Coder
    ' Date Created: 10/1/04
    ' Phone: [phone]
    ' SSN: 111-22-3333
    ' Eye Color: Green
    ' Maiden Name: None
    ' Blood Type: AB-
    ' Mother's Maiden Name: None
    ' Favorite Car: Pontiac Aztek
    ' Personalized License Plate: "Tek-ie"
    '*************************************************

Now imagine something like this exists for every function and you're reading the source code... Annoying.

Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have.

Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.

[arethuza]

Reading this discussion (and posting a comment about s-expressions) got me reading about Lisp[1], and then wondering about contemporary Lisp implementations, and then to Arc where I found this amusing comment by our host:

"Object-oriented programming generates a lot of what looks like work. Back in the days of fanfold, there was a type of programmer who would only put five or ten lines of code on a page, preceded by twenty lines of elaborately formatted comments. Object-oriented programming is like crack for these people: it lets you incorporate all this scaffolding right into your source code."

http://www.paulgraham.com/noop.html

[1] I was paid to program in Common Lisp for about 6 years. However, this was a while ago so I was attempting to refresh my memory.

[slurgfest]

What is interesting about reading this discussion is that all of the 'examples' used in order to show that comments are bad are totally implausible. On the other side, the situation of 'no comments at all' is actually ubiquitous, in reality.

Writing out what you are doing takes a little work, and requires at least briefly thinking about it. It also means you can be embarrassed if your code is doing something irrational or unintended, and looking at everything again when you make major breaking changes.

By Occam's Razor, it seems more likely that complaining about comments is driven by an unwillingness to produce them more than actual practical problems created for others by their presence.

[creativename]

Yeah, that's exactly the kind of formality and over-commenting that I meant by "I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.)". I saw a lot of examples of that at my old employer where they had tried (and failed) to automate some of their documentation years and years ago.

It's nice to have a brief description of what a class (or in many cases, a method) is intended for, etc. As others have said, it saves time each successive programmer from having to fully understand all of the source code.

[lawn]

Ah I see, misunderstood a bit.