Tuesday, June 21, 2005

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!


  1. When you say you used the original Dartmouth version of BASIC, does that by any chance mean that you were a student at Dartmouth in the 60s?

    -rich schwartz

  2. No Rich, I was Down Under here in Melbourne, when using that original form of BASIC -- "Beginner's All-purpose Symbolic Instruction Code" wasn't it -- first while teaching in high schools in the 1960s and then (atfer joining IBM Australia) some of its variants that followed in the early 1970s. In those days IBM had the CALL/360 time-sharing service follwed later by CALL/370. A decade or more before the IBM PC appeared and Microsoft got into the act.

    Are you of that vintage, or just wondering? Were you at Dartmouth College? BASIC in all its flavors certainly popularized computing for the masses.

  3. I'm not quite of that vintage. I was at Dartmouth in the late '70s and early '80s. I knew the professors who invented BASIC, and one of students who wrote the first compiler in the '60s was also a professor when I was there. In fact, he taught the intro CS course that I took. I used the versions 6 and 7 compilers (never interpreters at Dartmouth!). BASIC 6 had subs with parameters, simple functions (limited to a single argument), device-independent graphics (but there were only a handful of graphics-capable terminals on campus), fully dynamic strings and a good library of string-handling functions, and a whole set of features for doing matrix math on two dimensional arrays; but it was still all GOTOs for flow of control and variable names were limited to a single char plus a digit. Version 7 brought in long variable names and proper functions along with modern DO WHILE, IF... THEN... ELSE and CASE statements. There were no classes and objects back then, of course, but BASIC 7 was every bit as good a langauge as the Pascal of it's day -- and maybe better for a lot of purposes given Pascal's weakness at string handling, but it suffered from the bad reputation of all the terrible versions that were in world outside of Dartmouth, especially the early Microsoft BASIC. Credit where credit is due, however: VB, which was compiled and added objects and classes, did more to rehabilitate BASIC than anything else. VB was, in fact, based on the ANSI standard that was in turn based on Dartmouth BASIC 7.