The Mudcat Café TM
Thread #28443   Message #353234
Posted By: Jim Dixon
07-Dec-00 - 04:25 PM
Thread Name: BS: Is this comprehensible?
Subject: RE: BS: Is this comprehensible?
I got out of the programming business a long time ago. I was a programmer for about 12 years in the 1970's and 80's. (I wrote in COBOL. I'm not very familiar with Pascal, but it's easy to guess what your program is doing.) My technological knowledge may be mostly obsolete, but I'll tell you what I think anyway.

In real life, it's not likely anyone would ever write such a short program as a stand-alone item. It could only be an exercise, an experiment, or a small part of a much larger program. As a professional programmer, you would write hundreds of modules of this size in a year's time. Think of yourself a year from now looking back on this page and trying to remember why you wrote it, and trying to remember what distinguishes this particular module from the hundreds of others you have written. Or think of yourself looking for a particular program that you had written a year earlier, flipping though a stack of similar programs, having your eyes land on this one, and wondering for a second or two whether this is the one you were looking for.

(If you haven't done this with programs, maybe you have done it with songs or tunes.)

What would help you most? A title! I know your program already has a title -- "wages" -- and this might be sufficient for the computer. If you type RUN WAGES, it will probably run the right program. But in real life, it's not likely that a sizeable company would have only one program of this size that deals with wages. You need something more descriptive.

I'd say a program (subroutine, whatever you want to call it) of this size deserves about one or two lines of explanation.

Let's go back to the music analogy. Suppose you've got a stack of tunes that you've written down and performed at various times. You're looking for one that you've used before, so you can use it again. What would you like to have written at the top of the page, to help you find the one you want? You'd want a title for sure. But you may have several versions, for example:

Turkey in the Straw
Turkey in the Straw in G
Turkey in the Straw in D
Turkey in the Straw with guitar chords
Turkey in the Straw arranged for guitar and fiddle
Turkey in the Straw with tablature for mandolin
Turkey in the Straw parody for George's birthday

Sure, any programmer can read the code and figure out what it does, just like any musician can read the notes and figure out what a tune sounds like. But when you're flipping through pages looking for something, and you're in a hurry, you want something that will save you time. That's what good comments do.