Code comments - how old is your code?
-
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 comment for myself, because I know I'll be coming back and wondering why I did things the way I did. Always good for a laugh. :)
Give me coffee to change the things I can and wine for those I can not! PartsBin an Electronics Part Organizer - An updated version available! JaxCoder.com Latest Article: Simon Says, A Child's Game
-
I like Hungarian notation. When you have a single Windows Form with several hundred components on it across many layers of tab sheets and panels, knowing if you are looking at a button, label, or textbox component by its name in the code really saves you time. I do this in my C# code too, which has a lot less components per form. I view variable names as a cognitive map. Start with the big picture and then get more precise. So which component is it? Then which area does it live in? Then what does it do? txtLoanAmount is very clear what I'm dealing with. If I just saw LoanAmount, is it a label or a textbox or the value stored in memory to be used by the textbox? Let me see that tooltip - oh there goes a second or 2 waiting for it to pop.
Bond Keep all things as simple as possible, but no simpler. -said someone, somewhere
Yes; everthing has it's place. I name all my UI controls starting with "Ux..". I see some code where all their properties, variables, column names and controls are all names using lower case letters and expecting the compiler to sort it all out.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
I am perfectly in agreement with you.
Greg Utas wrote:
I have absolutely no tolerance for markup noise in comments, like Doxygen
I have the impression that this is becoming more and more the standard practice - it may be a different system from Doxygen, but the principles are the same. Let me extend it to lint comments. A few years ago, I cleaned up a code base that was soaked with lint comments to suppress specific lint warnings, yet a complete system build returned more that 23,000 lint errors and warnings. The developers were so used to seeing hundreds of them even for small unit compilations that they overlooked the warnings. Every now and then they made 'cleanups', which amounted to adding even more lint comments to reduce the number of warnings in the unit that was their responsibility. I set out to define a lintfile that would globally suppress the warnings we defined as ignorable, and for the remaining ones, modify the code so lint kept quiet. (We also redefined a number of warnings as errors, failing the build.) The source code became a lot more readable with all those lint comments out of it! I earlier worked with a company using/writing open source code: The coding rules required that a .c file contains a single function only. Common practice was to write very small functions, with bodies typically in the range of 5 to 20 lines. The problem was to see the code, you had to page down to the third screenful: Every file had to include an extensive copyleft / license statement. This caused the code base to have 80% comment lines. I very much like the statement made by Gary R. Wheeler, above: "If it can be said in code, say it in code. Otherwise say it in a comment." Whether it is intended for a documentation system (such as Doxygen) or just because company standard requires it, I see lots of function header comments that copies the function name, argument list a comment, with type/class and all. In most cases, the 'explanation' is nothing more than expanding a quite self-documenting name to a sequence of words, like 'int numberOfApples -- integer number of apples'. Or a fuction named 'CalculateTheTotalBill' providing an explanation 'This function calculates the total bill'. If you don't have anyting to say, don't say it! I would like to add to Wheeler's statement: "The primary purpose of the code is to show WHAT is done. The primary purpose of a comment is to explain WHY it is done."
I'd substitute HOW for WHAT ...WHAT are the consequences; which may not be "what" was expected.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
I never write comments. As it happens, I just hired a junior and he loves comments. He writes all sorts of useless comments like // set the variable. I told him not to do that because we can read code. Point is, he doesn't read code that well yet and the comments help him see what happens. He also writes comments like // why does this work? So he'll be reminded to ask me. One time we rearranged some code and all of his comments had to moved and/or changed as well. People sometimes forget that comments are just like code, they're hard to write well and they need maintainance just like code. Comment maintainance is rare and so most of the time comments are just as unclear as the code, outdated or even plain wrong. I rarely trust a comment and when I see them I'll try to change the code so they won't be necessary anymore. That's not to say I never write them. I once worked with a library (Crystal Reports, 'nuff said) where setting one property would set another one to null. So the order in which I set specific properties had to be very specific too. Needless to say I wrote a comment saying // do not switch these lines around, the person who wrote this library was drunk and drugged and the order somehow matters.
Best, Sander Azure DevOps Succinctly (free eBook) Azure Serverless Succinctly (free eBook) Migrating Apps to the Cloud with Azure arrgh.js - Bringing LINQ to JavaScript
His commenting may be providing him with "thinking space" ... the same way some people doodle. I expect he'll outgrow it.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
one of my products is 23 years old now since i launched it (started writing it in the late 90's), written in vb6. I sold over 1000 copies back in the day (and even sold a new one a year ago). I still have quite a few users who pay support (and a few who don't) and dont see the need to change or upgrade to my newer version coz it does everything they want and they are comfortable with it. my newer version was launched 2010 and is a net framework product, so i suppose 13yo for that is getting quite aged these days, but again i have loads of customers on it. I am a compulsive 'commenter' (always have been) since the 70's, even though the code is never likely to be seen by anyone else, and now i'm in my 60's (and still coding), the grey matter aint as sharp as it once was there's a definate advantage when i need to make mods, and imho code that aint documented aint complete. GL
Yes ... commenting can be seen as an investment in terms of when it comes time to "sell the company". One man's noise is another man's salvation.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
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.
Definitely for myself, though most of the comments nowadays seem to be
// TODO: fix this bug:laugh:Latest Articles:
A Lightweight Thread Safe In-Memory Keyed Generic Cache Collection Service A Dynamic Where Implementation for Entity Framework -
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 started programming in the late 70's so the only real option was assembly code for the devices I was programming for. It pretty much cemented the idea that I should be commenting my code. It's a practice that I kept throughout my career. Commenting was for my own benefit and for anyone who might be modifying my code. I always made the assumption that the person inheriting one of my projects wouldn't necessarily be a very knowledgeable programmer so good commenting was needed.
-
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.
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?
-
Never say never :laugh: I write them like once every few years whenever I find some weird ass third party component I really can't ditch :)
Best, Sander Azure DevOps Succinctly (free eBook) Azure Serverless Succinctly (free eBook) Migrating Apps to the Cloud with Azure arrgh.js - Bringing LINQ to JavaScript
-
Absolutely do matter, anyone tells you otherwise does not have 40 years experience. The concept of "self-documenting" code is nice, sometimes do-able. But the time it takes to write a comment (or a few comments) for code that is non-trivial is saved many times over as that code is revisited in coming *decades* (think the build up to Y2K when we needed to figure out code written between 1965 and 1990). Not commenting is short-sighted and, I think, selfish and arrogant of the developer who assumes: 1) later developers are as good as he thinks he is 2) his time is too valuable to be wasted doing non-coding tasks. Sorry, personal pet peeve of mine picking up process control C code written in the mid-1990s with zero comments that does not work.
-
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.
Comment for yourself. Some devs will read them... some... if they are coherent and make sense to a different person. And then some devs refuse to take any initiative... so good luck with that.
Jeremy Falcon
-
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.
