Re: Reviving REMARKS

"Peter Lacey" <lacey@xxxxxxx> wrote in message
news:42F11CFC.1880825E@xxxxxxxxxx
> Richard wrote:
>> Actually the point about _self_ documenting is that it doesn't need
>> remarks or comments.

> That's incomplete. I have come across innumerable examples of code that
> were perfectly easy to follow but were completely inexplicable. An
> example - a price was determined by looking things up in a 2-d table;
> easy; but then $1.26 was added. No indication why; nobody could tell
> me; I eventually found a five-year-old memo by an engineer that cleared
> things up. Now if the programmer had included as a comment, a reference
> to the memo and (possibly) where to find it I'd have saved several hours
> of exasperation.
> There are many other possibilities where the code, by itself, doesn't
> tell you what you need to know. (I'm speaking of maintaining the code,
> of course).
>
> PL
The code was self documenting..it was saying lookup a price and add $1.26.
The reason why is a not part of the code - that's part of the system
functionality and should be documented with the system function guide or
whatever you call it. If someone was to ask a non programmer what the price
would be for a customer you wouldn't ask them to read code would you?

In addition using something like 77 [reason]-SURCHARGE PIC 9.99 VALUE 1.26
may have helped even more.

JCE


.