Code comments - how old is your code?
-
We have code in our current product that was written in 2000, and the commenting has always been up to the individual. We do have a naming standard, but it's pretty relaxed (with the exception of Hungarian notation: use that, and we'll nuke your cubicle from orbit just to be sure). Our only commenting standard is for entries in our change history which are automatically extracted and collated into an HTML document by our automated build process. My personal practice is based on something Dan Saks, former Secretary of the ISO C/C++ Standards Committee, once said: "If it can be said in code, say it in code. Otherwise say it in a comment." This means choosing expressive, meaningful names and organizing things in ways that reflect the process you're implementing. All of this is very squishy and more art than science. All this is well and good until you throw someone new into the mix. We hired a new guy, a couple of years experience and very sharp. He had trouble with my code :confused: :rolleyes: , not so much reading any particular piece of it, but getting the big picture. He's helping us transition from SourceSafe to git source control. In the same vein he's advocating for other changes to our process, including automated code documentation. He suggested doxygen, which looked great until we discovered the doxygen application was weak. Doxygen approaches the code base as if all of it belongs to a single executable. Our product is a Windows application and several services, along with several DLL's. We found DoxyPress[^], a fork of doxygen that seems to remove doxygen's limitations. We're treating the automated documentation as a roadmap, a guide to navigating the code base. We'll see how good a job we do.
Software Zen:
delete this;Gary R. Wheeler wrote:
We found DoxyPress[^], a fork of doxygen
Thank you for the reference. On the face of it, seems to be what I've been looking for. I have a love-hate relationship with Doxygen: love that it generates the docs, hate how buggy and limited it is.
Mircea
-
We have code in our current product that was written in 2000, and the commenting has always been up to the individual. We do have a naming standard, but it's pretty relaxed (with the exception of Hungarian notation: use that, and we'll nuke your cubicle from orbit just to be sure). Our only commenting standard is for entries in our change history which are automatically extracted and collated into an HTML document by our automated build process. My personal practice is based on something Dan Saks, former Secretary of the ISO C/C++ Standards Committee, once said: "If it can be said in code, say it in code. Otherwise say it in a comment." This means choosing expressive, meaningful names and organizing things in ways that reflect the process you're implementing. All of this is very squishy and more art than science. All this is well and good until you throw someone new into the mix. We hired a new guy, a couple of years experience and very sharp. He had trouble with my code :confused: :rolleyes: , not so much reading any particular piece of it, but getting the big picture. He's helping us transition from SourceSafe to git source control. In the same vein he's advocating for other changes to our process, including automated code documentation. He suggested doxygen, which looked great until we discovered the doxygen application was weak. Doxygen approaches the code base as if all of it belongs to a single executable. Our product is a Windows application and several services, along with several DLL's. We found DoxyPress[^], a fork of doxygen that seems to remove doxygen's limitations. We're treating the automated documentation as a roadmap, a guide to navigating the code base. We'll see how good a job we do.
Software Zen:
delete this;Maybe I'm an outlier in this, but I have absolutely no tolerance for markup noise in comments, like Doxygen. They should read like properly written plain text, often in sentences. No one working on the code can be bothered to run it through some mofo tool to look at the results. It matters not whether they're looking at an interface or implementation. It's useful to have higher-level documents that provide an overview of the system, but those are not alongside the code and should be written in Markup, Word, or whatever.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
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.
"TO DO: ..." is my current favorite.
"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
-
Maybe I'm an outlier in this, but I have absolutely no tolerance for markup noise in comments, like Doxygen. They should read like properly written plain text, often in sentences. No one working on the code can be bothered to run it through some mofo tool to look at the results. It matters not whether they're looking at an interface or implementation. It's useful to have higher-level documents that provide an overview of the system, but those are not alongside the code and should be written in Markup, Word, or whatever.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.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 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
-
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.
Yesterday I edited some code and noticed that the last edit was done 22 years ago to the day - by me. And yes, the comments were useful.
-
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 use comments mostly to remind future me that this needed to be done this way because ... and then future me tells me that that's no longer the case - these days we have something called *new buzzword* ... So we sort of complement each other. 25+ years for the same employer -- and some of those products (from even further back in time) are still with us ... Some unfortunately, some rightly so.
-
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 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
-
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.
Long back, had inherited a code like this:
bool funcName( five arguments of different types )
{
/*
200 lines of C++ code
*/
return true;
}No comments in the code, rather the entire code was commented out. Unfortunately, could not get my hand on the coder who created this, he had resigned.
-
Decade+ old code and my beautiful friend and I still go through stuff we wrote back then and ask ourselves "What the :elephant: was I thinking?" That's not a slam on what the code was doing. I mean, it works perfectly fine, but how we did it back then compared to how either of us would do it today. The comments help, but they can't save us from ourselves as we learn more and more.
Asking questions is a skill CodeProject Forum Guidelines Google: C# How to debug code Seriously, go read these articles.
Dave KreskowiakIndeed. Sometimes the dawning of realisation can be a lot quicker. More than once I've written a comment (for my future self) and having spent an hour writing code, suddenly "hear myself" explaining it in the comment and think "That's a *&@$$@% stupid way to do this". Then I spend the next 5 minutes massively simplifying it to the point where it's so blindingly obvious that it doesn't need a comment at all. Sometimes I just realise that a variable name seemed great when I first defined it, but after using it there's probably something better. Commenting can be like pair code review - but with your future self instead of someone next to you.
Telegraph marker posts ... nothing to do with IT Phasmid email discussion group ... also nothing to do with IT Beekeeping and honey site ... still nothing to do with IT
-
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.
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
-
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
Sander Rossel wrote:
I never write comments.
Sander Rossel wrote:
That's not to say I never write them.
:confused:
-
Sander Rossel wrote:
I never write comments.
Sander Rossel wrote:
That's not to say I never write them.
:confused:
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
-
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.
charlieg wrote:
Do comments even matter any more, or am I flattering myself?
Comments matter A LOT. Although, going through the previous replies I can see a contrarian trend ("I don't write comments", "code should be self-documenting", etc.). Sorry, but I find it ludicrous, at least in my line of work. Just two days ago I was working on this code:
/*
Transformation parameters from previous ITRF frames to ITRF-2008
Data from http://itrf.ign.fr/doc\_ITRF/Transfo-ITRF2008\_ITRFs.txt
Epoch is 2000.0. Compared with the source, this table has signs reversed
because we go from ITRF_xx to ITRF2008, translation units are meters and
scale units are ppm.
*/
const double pre_2008[2][14] = {
// tx ty tz dsc rx ry rz
{ 0.0019, 0.0017, 0.0105, -0.00134, 0.00, 0.00, 0.00,
-0.0001, -0.0001, 0.0018, 0.00008, 0.00, 0.00, 0.00}, //ITRF2000
{ 0.0020, 0.0009, 0.0047, -0.00094, 0.00, 0.00, 0.00, //ITRF2005
-0.0003, 0.0, 0.0, 0.00, 0.00, 0.00, 0.00}
};Pray tell me, how would you write this in a self-documenting way? If I wouldn't have put that comment block there, would anyone (myself included) had been able to figure out what's going on? So, for your own sanity and for the sanity of those around you, please, keep commenting!
Mircea
-
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.
My oldest code that I maintain is no more than ~10 years old (have moved companies, products have been EOL'ed, etc.), but I've always been a compulsive commenter. The comments mostly help me, six months down the line.
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows. -- 6079 Smith W.
-
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 find it depends on what language I'm writing in and, to a certain degree, what the code is doing. In general, I'll have more comments when I'm writing C code than I do for C# and Java. I've got some C code that does some quite involved data manipulation. That code has both in-line comments and a notice at the top that says "read and UNDERSTAND the XXX page on the project wiki before you do anything with this code." What it's doing is so complex both high-level and low-level block comments are needed for anyone besides me to modify it. I've also got some C code that does the equivalent of serialization; that code has no comments beyond "save the data via serialization" As with all things coding --- it depends.
Be wary of strong drink. It can make you shoot at tax collectors - and miss. Lazarus Long, "Time Enough For Love" by Robert A. Heinlein
-
Maybe I'm an outlier in this, but I have absolutely no tolerance for markup noise in comments, like Doxygen. They should read like properly written plain text, often in sentences. No one working on the code can be bothered to run it through some mofo tool to look at the results. It matters not whether they're looking at an interface or implementation. It's useful to have higher-level documents that provide an overview of the system, but those are not alongside the code and should be written in Markup, Word, or whatever.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.I tend to agree with you, but my team is getting old. Four of us together have well over a man-century of experience with this product line which has been through several major evolutions. Our code base currently consists of 167 folders containing 3,450 files, and according to CLOC[^] a little over 900K lines of code. Introducing someone new even when they're smart means giving them some way to learn their way around. Even without "markup noise" DoxyPress creates useful documentation. Adding markup can improve the roadmap without desecrating the sacred texts.
Software Zen:
delete this; -
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 used to write comments all over the place that know one reads, even me. Nowadays I write comments so GitHub Copilot can generate code off of it auto-magically. 😁
-
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.
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.
-
Gary R. Wheeler wrote:
Hungarian notation: use that, and we'll nuke your cubicle
:laugh: :thumbsup:
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
