Code comments - how old is your code?

[jmaida]

:) I agree. I do it for me first. That controls the level detail so that I don't have to re-edit my comments constantly. If someone else has to read it, it helps them too!

"A little time, a little trouble, your better day" Badfinger

[Derek Hunter]

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.

[Jonas Hammarberg]

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.

[Sander Rossel]

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

[Amarnath S]

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.

[DerekT P]

Indeed. 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

[_WinBase_]

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

[Slacker007]

Sander Rossel wrote:

I never write comments.

Sander Rossel wrote:

That's not to say I never write them.

:confused:

[Sander Rossel]

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

[Mircea Neacsu]

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

[Daniel Pfeffer]

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.

[JudyL_MD]

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

[Gary Wheeler]

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;

[decaffeinatedMonkey]

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. 😁

[WPerkins]

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.

[Matt Bond]

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

[kmoorevs]

Since this seems to be two questions, I'll answer in two parts: Code comments: I use comments very sparingly, really only when the code is complicated. Yesterday I wrote more comments than I typically write in a month, describing for myself the layout/elements of several multi-dimensional arrays. I do find that I comment more these days that I used to. How old is my code? My company's flagship product was released to the public at a trade show in the summer of 2K. Since development started around 1.5 years before that, there is code that dates back to '98 when I got hired...so around 25 years ago! :omg:

"Go forth into the source" - Neal Morse "Hope is contagious"

[Cpichols]

FWIW I read comments others have written. Even if I'm the only one who will ever read my comments, that makes them worthwhile. I try very hard to make my comments clear and concise to improve the chances that they will be read.

[maze3]

past maze3 and future maze3 conspire to sabotage me and give me more work

[Lost User]

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