[time-nuts] Getting GPIB to work on HP5382B Universal counter

Heinzmann, Stefan (ALC NetworX GmbH) Stefan.Heinzmann at alcnetworx.de
Wed Oct 14 10:19:43 UTC 2009


Dave Baxter wrote:

> As my old college tutor kept trying to drum into us, the programs
> purpose and function should be easily read in the comments.  The "code"
> is the translation from your comments, to get the machine to do your
> bidding.

> 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