[time-nuts] [OT] Software code: Was RE: Getting GPIB to work on HP5382B Universal counter

Dave Baxter dave at uk-ar.co.uk
Wed Oct 14 12:36:32 UTC 2009


Sorry Stefan..

Yes you are of course correct in that no compiler/interpreter (I know
of) checks comments for "correctness".  But that's not the point of
them.   They need to be there to describe the intended purpose of the
code, above the actual implementation.

If you have to modify code (yours or someone else's) for some reason,
and there are related comments there already, you need to also comment
the modified code.  What changes and why etc, and date it too.

If there are no comments, feel free to add some of your own.

As earlier, so you know what's what some time later, or as you say, you
have no clue as to what is correct, or otherwise.

Personally, unless it's a minor change, I find in the long term it's
best to comment out a buggy block, original comments as well, then
either paste the code only back in to debug and fix it, but then write
new comments relating to the new code, and again why there was a change
needed.

If it's a really bad problem, perhaps archive the buggy module in it's
entirety, and start again, with a cross reference to the original module
and the archive it's in, for completeness.  Many a code change has been
done in good faith to fix one prominent problem, only to break something
else unintentionally.

As David Partridge said, so the next poor sap can understand what
happened, and why.

It's a discipline thing, no compiler or IDE can help you with that.
It's a "wetware" issue.

You want to try to work on code that started life as Borland C (from the
DOS world) and is now C++ as used in a creaky open source GCC compiler
tool suite, but authored originally by the Dutch!   Believe me, any/all
comments are good, even if I have to copy/paste into/out of Google's
Translation tools!

Cheers.

Dave B.


> -----Original Message-----
> Document what you do, in the source comments, line by line at times!
> You'll save a lot of time when you come back to something later, even 
> only a few days time!

While the general advice is sound, comments are a mixed blessing. The
main problem with them is that they're in no way checked for their
correctness, as the compiler or interpreter ignores them.

Quite often that leads to comment rot: When bugs get fixed and features
added, the comments don't get updated and get out of sync with the code.
Eventually you get conflicting information from code and comments and
have to figure out which one's right. An old programmer's saying is: If
code and comment disagree, they're probably both wrong.

Comments are important, but even more important in my opinion is to try
to write code in a way that is understandable without a comment. Try to
say it in code, and put in comments where that fails. Don't try to
duplicate what the code says in a comment. Rather, explain the general
idea or method.

Anyway, just my 0.02?

Cheers
Stefan



More information about the time-nuts mailing list