If you peruse my example and walked away from it thinking that it stands as an example of why to comment every line, use pretty formatting of comments, put comments at the end of lines where they have to be adjusted by anyone making changes to the code, etc, etc, etc - then you missed the point.

My last paragraph of what you were responding to said:

Also note that I don't actually write uncommented code. But my comments are about different aspects of the code than the mere mechanics of what each line is doing...

Stare at that carefully.

The sample commenting examples that you gave resulted in comments whose formatting would be a maintainance issue that so closely duplicate what the code says that there is little added value. Secondly the very verbosity of the comments led you to use a useless variable and a confusing comment. You claim you wouldn't use such a variable name in practice, but I only have what you wrote to judge by. And in what you wrote you used a useless variable name and a useless - confusing - comment.

The sample code I pointed you at is commented. But it is commented in a completely different way and style. Plus I can tell you how that style would change in a slightly different circumstance.

I comment. Yes. I comment intent. I highlight key points. I do not explain my algorithms. I do not explain my variable names. I do not produce a separate document for the human and the computer. And above all I have a commenting style that is not going to be a lot of work to maintain.

So if you need to change the code and make it do something else, or if you need to understand the mechanics so you can do something similar, then you will need to read the code. Humans should be able to figure out how the code does what it says it does.

Now you claim I misunderstood you and you never meant to advocate play by play commentary on the mechanics. But the examples that you gave were play by play commentary on the mechanics. The statement you made (that I cannot disagree strongly enough with) is that there is no such thing as overcommenting. The formatting of comments that you advocated poses a serious maintainance problem. You claim that overcommenting only accounts for perhaps 0.1% of comment related problems out there.

I am sorry, but I cannot reconcile these two points of view. What you are saying now does not fit what you showed as an example of what you think people should do.

I have dealt with problems due to overcommenting, poorly maintained comments, comments that only make sense if you are in the original author's point of view, comments that cover for poorly thought out code, comments whose formatting makes code hard to tinker with...and most of these problems would have either not been there or been lessened if the original programmers understood that not all comments are good.

In fact for every one of those items I either saw them in your examples of how to comment, or I saw you doing things that have lead to these errors in code that I have worked with.

Now you claim that the style of commenting that I demonstrated is what you were attempting to advocate. Well it certainly isn't what you describe. So let me explicitly explain the style that I follow:

1. Every function that is part of the public API gets a brief description of input, output, and action. If the function is not documented, it is not public. If the function name starts with an _, it is probably not even (usefully) callable.
2. The overall package gets a brief description of what it does.
3. If the package is somewhat private (ie for me and people I work closely with), documentation goes inline in front of the described function.
4. If it is to be more generally used, documentation goes into pod.
5. Key conceptual points may be highlighted with comments.
6. Function names describe what they do. If that means long function names, so be it.
7. Variable names describe what they do. For instance flags should be questions which the current value is the answer to. If the meaning of a variable is unclear, then it needs a better name, not a comment.
8. Variables are not documented unless they are part of the public API. Documentation of variables is to inform others what may be used, not to explain what the variable does.
9. The formatting and naming scheme is consistent.
10. The formatting of comments is chosen to not cause any issues upon maintainance of code. This generally means being on separate lines from code, and means a minimum of fancy formatting.
11. The mechanics of the code are not documented unless it uses a non-obvious API. In that case the other API is commented about inline.
12. Whenever reasonable, large functions are broken into a series of smaller functions so that the body of the function reads as a series of hopefully self-descriptive function calls.
13. Wherever I spot a significant opportunity for error, I place an error check with an informative error message in case things go wrong. The error message is intended to serve as a useful comment both upon reading the source and during any failure condition.
14. Functions are grouped into modules. Within a module functions appear in alphabetical order. (This is a personal style settled on after finding that initial attempts to divide by what the functions did inevitably broke down when at different points in the project I thought differently about the code.)

I describe this as being, as much as is feasible, the code standing as its own comment. What cannot be done by making the code clear is commented. Whatever can be done by making the code clear, is.

A better way to put this might be that I do not comment on the code. I comment on the usage of the code and I comment on other code. I comment on desired changes, I comment about what is critical, and what the external dependencies are. But the code at hand should be readable and should stand as its own comment.

Now with all that in mind, please go back and read my example again and compare to this detailed summary. Does my code not fit my description? Does my code need detailed comments about how it works? Do I, despite that, comment in a useful way while requiring a minimum of work to maintain the comments as the code changes?

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.