Code comments - how old is your code?
-
There has been a fairly recent crusade against comments. Some claim code should be self-documenting and that comments are somehow evil. You know what's documenting? Documentation... like comments. Self-documenting? WTF? There's nearly zero code ever written that explains WHY it does what it does or WHY it was changed to do otherwise. I guess you can enforce tying commits to cards and chase down the commit that changed the code and then the card that brought that commit. Alternatively, maybe a comment isn't such a bad thing. Has nobody written a VS plugin to just turn all comments on/off? Is it really just that developers hate documentation so much they'd rather claim their code does all the documentation for them? Because that's just how great their code is? Do people not use XML comments so people get intellisense on what they are calling? Do they think making that block descriptive is some massive chore?
That crusade against comments has been going on for many years, where I have been. The major exception is huge copyright/left comment blocks topping every source file and extensive comment blocks heading every function, repeating the function name, the the types and names of all parameters of the function declaration, only doing it in 10-20 lines instead of one, cluttered with typographic markup. I have been heavily criticized for my habit of adding a lot of explanatory ("why") end-of-line comments - end-of-line because I like to see the entire function/method in a single screenful rather than three. I also have a habit of aligning the comments from col 80, so that they do not visually disturb the code itself - you look at the comments (only) if you wonder "why". A number of my critics also love to open three source file windows side by side, so narrow that they usually won't see my comments, which are outside of their windows :-)
-
There has been a fairly recent crusade against comments. Some claim code should be self-documenting and that comments are somehow evil. You know what's documenting? Documentation... like comments. Self-documenting? WTF? There's nearly zero code ever written that explains WHY it does what it does or WHY it was changed to do otherwise. I guess you can enforce tying commits to cards and chase down the commit that changed the code and then the card that brought that commit. Alternatively, maybe a comment isn't such a bad thing. Has nobody written a VS plugin to just turn all comments on/off? Is it really just that developers hate documentation so much they'd rather claim their code does all the documentation for them? Because that's just how great their code is? Do people not use XML comments so people get intellisense on what they are calling? Do they think making that block descriptive is some massive chore?
-
Just hit an interesting thought and would like veterans' perspective. I support a product that has over 20+ years of accumulated history. As I was writing some comments to explain why or what some code was doing, I've found that the #1 person who read my comments was me. Do comments even matter any more, or am I flattering myself? Filed under hmmmm
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
I guess I should have provided context on what I mean as a comment. For as long as I've been writing code, I outgrew quickly code comments that say "increment the pointer" and other trivial stuff. I also like *limited* Hungarian notation: certain prefixes that over time just help me scan the code. Years ago, I picked up the habit that every pointer begins with a lower case p. Key was readability. As for oxygen and other tools like that, they sometimes help understand the overall system (especially call trees) but development tools have made such advancements that most of the doc has been replaced by tool features (hovering over a variable for example). The best tool I've ever used is Understand from SciTools. Unfortunately, they moved from a perm. license model to monthly fees, pricing it out of my market. Rather than what, I try to explain why the code does what it does. Example of the table of data - that's what and you can infer why. In my case, I have a piece of common code that runs on 4 different platforms. Thelatest platform has some issues to be worked around, and I found myself trying to explain why. It then occurred to me that I knew the product was reaching end of life, no one will likely read this, just comment in the SVN commit. After reading all of the replies to my question, it might be wordier, but breaking up the code into 4 different methods (each supporting a specific device) is probably the cleaner approach. Thanks for the insights.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Just hit an interesting thought and would like veterans' perspective. I support a product that has over 20+ years of accumulated history. As I was writing some comments to explain why or what some code was doing, I've found that the #1 person who read my comments was me. Do comments even matter any more, or am I flattering myself? Filed under hmmmm
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
Sometime in the 1970s one of our users reported a problem entering a date for a future event. The code was not written by us, but we had the source, so I pulled up the code to see how it worked. I found this comment (PDP-10 assembler) "Thirty days hath September, all the rest I can't remember, except February which never works anyway" There was no code to handle leap year! At least the comment helped us know we were in the right place. That isn't the worst comment I found in code from that source, but the worst would violate nsfw rules.
-
Sometime in the 1970s one of our users reported a problem entering a date for a future event. The code was not written by us, but we had the source, so I pulled up the code to see how it worked. I found this comment (PDP-10 assembler) "Thirty days hath September, all the rest I can't remember, except February which never works anyway" There was no code to handle leap year! At least the comment helped us know we were in the right place. That isn't the worst comment I found in code from that source, but the worst would violate nsfw rules.