>Hi Jim,
>I agree for the most part on inline commentary in this manner. This was the way I was formally taught to document code, but I found it led me easily to a bad habit. The bad habit being that my psuedocode typically states *what* I am doing as opposed to telling me *why* I am doing it. I've found that at the time I'm writing new code, I'm running full speed ahead and know easily *what* I need to do next. But when somebody else looks at that code, or if I go back and look at it some time later, I tend to look at the *what I am doing* comment and say "Duh... I can see that" So now my own standard is to key in my psuedocode in a different form, so as to explain *why* I need to do a particular step. i.e. -
>
>* Get the correct records for the Customer just entered (instead of this)
>*!* Retrieve customer records for id user entered to populate grid
> code doing so is here, possibly several lines
>
>FWIW - In regards to other parts of this thread, I think putting the AND/OR operator at the beginning of a continuation line is more readable than putting it at the end.

Rox,

A very wise man once told me, "Don't comment the obvious." For example, a comment like "* Select unused workarea" right before SELECT 0. Someone who doesn't understand the meaning of something like that has no business messing with the code in the first place. In fact, unnecessary and overly long comments can serve to make something less readable than it would be otherwise by breaking up the program flow.

Often what I do (and this, I think, is pretty common) is write the comments first, then fill in the code.

FWIW, I think that a big problem in maintenance is a lack of cohesion of a particular piece of code. In other words, code that is "too busy" and too long. Printouts of my stuff rarely run long than a page simply because I write cohesive code.