[randomdata]

To be fair, writing meaningful comments is really hard. So hard that the number of people who do it well is a small fraction of even the otherwise best programmers. To make matters worse, poor comments are worse than no comments at all. I can see why many programmers shy away from them.

* Comments that describe what the code does are a complete waste of time. The code already tells you what it does.

* Comments that describe why the code was written has more merit, but I cannot see how the following is any real improvement over the first point:

  // Investments of this type have always added the interest
  // to the principle. Who are we to question convention?
  $balance = $principle + $interest;

I am one of those poor commenters, so I really have no idea what could be said about that line that isn't already known. If you say not everything needs to be commented, then where does the line get drawn? In most cases, the vast majority of your code should be no less obvious than this.

* Some suggest the method signature and invariants should be documented, but that seems like just another exploitation of comments to deal with limitations of the language and is no better than putting annotations in the comments.

* I've seen code examples for using a given method in the comments, but that is better left to your test suite. Not only then can the reader see the example, but you can verify your method works at the same time without cluttering up the original codebase to boot.

If you are doing something weird, then yes, I am with you that comments are a big deal. However, if you are doing weird things on a regular basis I have to question your reasons for doing so. You shouldn't have to do weird things 99% of the time.

With that, teach us wise one. How can we all become great commenters so that we do not have to brush it off as something we do not have time for?

[astrodust]

Comments regarding methods should be added to clarify how they are intended to be used, and what the results should be expected to be.

Comments within the code should be used to highlight things that are not what they seem. They should answer any "WTF?" questions that naturally arise. A typical example is something like "Hack: Need to pass fifth argument as -1 to avoid crash in broken library".

Comments that act like descriptive audio are useless.

[randomdata]

I would love to see a good example of your first case. It is difficult to imagine and learn from it without seeing it action.

As I mentioned before, it seems the number of people who can actually pull off good comments are exceedingly small. I've looked at some prolific open source projects that have a decent amount commenting around method definitions as you suggest is good practice, but found the comments to be no more enlightening than just looking at the source code itself. I will assume they were just poor examples.

I do agree with everything else you said though.

[astrodust]

I find it's best to describe what the argument are, as short names are rarely enough, and the return values or values supplied to callbacks under various conditions.

An example would be:

"Verify account takes an account ID, an optional enabled flag which, if specified, will only search for accounts that have a matching enabled status. The default is to search against all accounts. The return value is true if the account is valid, false otherwise."

These are extremely important in loosely typed languages where there is little indication as to what constitutes an acceptable argument. In a more rigid language like C++ there are usually a lot more hints in the language about what the input and output is.

Still, in programming "by contract" it is important to manage expectations and comments can communicate a lot of this.

[randomdata]

Wouldn't that kind of information be better expressed in machine-human-readbale formats outside of the code that can be used to not only convey the information to the reader, but also verify that the description does as it says it does?

I will agree that some of that information is worth writing down, but I'm not yet convinced a comment within the code is the right place for it.

> These are extremely important in loosely typed languages where there is little indication as to what constitutes an acceptable argument.

Isn't that just pushing language "flaws" into the comments, not unlike annotations are being used here? I'll grant you that it is pragmatic when faced with lack of tools, but the grandparent suggested annotation comments were a bad idea but comments were a great idea, which seems contradictory to me in light of this.

[astrodust]

The only "machine readable" comments I've seen that are useful are those structured in a simple, non-intrusive manner that makes generating documentation from them more automatic.

Remember that comments and documentation are no substitute for proper testing that will expose usage errors. No amount of machine readable specification can prevent this, so it's often a waste of programmer time to produce.

[randomdata]

> Remember that comments and documentation are no substitute for proper testing that will expose usage errors.

Which is pretty much what I was getting at. Consider the following pseudo-code:

  Verify account takes an account ID, an optional enabled flag which, if
  specified, will only search for accounts that have a matching enabled
  status. The default is to search against all accounts. The return
  value is true if the account is valid, false otherwise.:

    account = new Account(id: 1)
    assert account.search does_not_include id != 1

It is human readable and machine parseable. You get your documentation, usage examples, and tests all in a place that is far better suited for the job, in my present opinion. I welcome being swayed though.

(I'm not sure that code even matches what your comment describes, but I couldn't really figure out what the comment was supposed to really intend the code to do, which brings me all the way back to my original points. Sorry.)