[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.)