Removing Comments from Software (a valuable tip)

Hao jiu bu jian le [pinyin Chinese, otherwise “Long time no see”].

I have been enjoying my grandson's first birthday, and also recovering from a 'flu shot (it's winter time here Down Under) and a major disk crash which eventually led me to spend several weeks rebuilding and reorganizing my main system. That's all out of the way, so now I can "get back in the blogging saddle" (with millions of blogs out there, I’m sure my absence wasn’t missed) ...

- - - - -

I've worked with many programming languages over the years (since the 1960s). I've never been a full-time developer -- because I've alwasy had lots of other duties -- but I still develop a fair bit of code as and when the need arises.

And I do try to write brief but useful comments as I go, and to change the comments as the code is maintained over time.

I just came across this valuable article at StickyMinds.com about an aspect of commenting code that is frequently overlooked: Write Sweet-Smelling Comments (by Mike Clark).

- - - - -

And still on the topic of the commenting software ...

I am one of theose "old timers" originally brought up on languages like FORTRAN and PL/I and BASIC (the original Dartmouth version, not the Visual Basic form) and COBOL and ASSEMBLER were in vogue. In those days, you wrote everything as source code "in the open" and placed your comments in that source code.

The source code was originally punched onto paper tape or cards or other inconvenient media types, you would often get only one overnight run to complile and test your program, and had to wait until the next day to wade a printout and see what had happened. Get a comma out of place, and you'd have to wait until the next night for another run. You learned to code extremely carefully and to be extremely patient! But at least all of your code was right there in front of you on the printed page, and not tucked away in obscure places.

Most assuredly I don't want to turn the clock back, but I do reckon that modern development environments in certain respects tend not to lend themselves to good coding practices including good commenting. I say this because there's usually a bunch of visual and other structures that are being developed that typically do not have any place for embedding detailed relevant comments. So maintaining modern applications can turn into a nightmare because there's no embedded commentary about the structure and behavious of these ancillary structures.

I know it from first-had experience with trying to maintain/improve such applications. Heck, I sometimes even have trouble understanding my own work after the passage of not too much time, because I had no decent way of embedding comments everywhere they were needed and so when I came back to it had trouble remembering all of the "nooks and crannies" that needed to be worked on (or at lthe very least checked again) to do proper maintenance.

Sometimes there would be design properties -- and even deeply embedded code -- lurking in dark and forgotten spots, sometimes only to be discovered by chance later on! (This might have been a non-issue if the client had been willing to pay for the many days or weeks of time needed to comprehensively document all of these things, but more often than not such detailed documentation is not budgeted for.)

Hence let me make a call to action for tools vendors all and sundry to build better commenting facilities into ALL design elements that form part of their application design and developmentproducts. This could be Lotus Notes, or Java, or .NET, or just about any other product from any vendor -- you name it!