I think I'm in a minority here, but the state of comments in some code is truly appalling, and the worst offenders are those who think their code is so clear or logical it doesn't need commenting.
I've worked with many such delusional characters over the years, and it always seems to be he ones who should know better, the "above average developers", and you can measure that however you feel.
The thing is, they are correct, or at least they would be if they were working on one-man projects. The code is clear to the author as it comes from their thought process. What's obvious to them is often far from obvious to everyone around them, and this state of affairs is made worse when using call-backs, events or making use of things such as multi-threading.
The argument is usually either "the code is self commenting" or "adding comments will confuse the code" and "comments become out of date quickly and therefore misleading". I'll briefly address these points now:
The code is self commenting.
Indeed, the code ideally should be, but how about a general overview of what happens? And is it really? The people who claim the code in such are often the authors of long, convoluted methods, with no clean responsibility, lots of inner classes or methods (depending on the language).
This code is difficult for others not familiar with it (often that equates to everyone other than the original author) to follow, but amusingly it is often tricky for the original author to understand when returning to code after some absence.
The times I've seen such developers struggle to understand what they were trying to achieve in a piece of code is frightening, but they normally get it fairly quickly as it comes from their imagination. If only everyone else was looking at it from the same perspective, then you may have a point.
Yes, the code can be self commenting, but to me this means well named methods with a clear responsibility, not a 40+ line method that covers all branches of execution.
Adding comments confuses or detracts from the code.
Well, it's often subjective, but I agree that adding too many comments does detract from the code and make it more difficult to understand. Having said that, a comment that briefly describes what a particular method is trying to achieve (something akin to JavaDoc or the .Net triple slashes if available) can be an immense aid to a tired developer trying to understand how something is supposed to work. This can occasionally even be a reference to the functional specification if you're lucky enough to have one. Such comments can be easily ignored if you find them offensive.
I'd also go so far at to say an occasional comment before a section of "non trivial" code can help both the initial development (I often use comments to help provide a skeleton and program into them) and future maintenance.
Comments become out of date quickly and therefore misleading
Then you're not treating them with the respect they deserve. Isn't that a bit like saying "it compiles so it will run?". Of course, tracing comments that need updating can be a chore, but if they are finely grained and focused on what is actually happening in the particular concern they are attached to, code and comment modifications can be performed hand in hand. Anything else, go to the specification.
In my opinion you should target your comments at others not yourself (although having said that my memory is sufficiently poor that I will happily use my own comments as a reminder). Assume little and ensure you give a decent starting point for further investigation at the very least. And for the love of god comment any gotchas or what you did to avoid them. Often we add code that looks out of place or redundant just to get around such things (yes, I know there may be a design flaw, but we'll code with a view to make a refactor as soon as we can go more easily and actually get the product out of the door (and that's a whole other post).
I could go on with this post, but in a nutshell I'm just sick of trawling through thousands of lines of uncommented code that should make perfect sense, but are complex enough to only be apparent to the author, and even then the author often struggles.
No comments:
Post a Comment