Re: Commenting (was: what is unclear about 01 02 03)

["James W. Kilgore" <qappdsn@xxxxxxx>]

Ed,

We have also used such a coding tool and took it a simple step farther.

We designed the application/program is psudocode which we would run through a
process creating source code.  The psudocode would be the comments and (before
external files) the appropriate /COPY statements would be included.  We would
write: USING CUSTOMER_MASTER AS UPDATE SECONDARY MATCHING BY COMPANY_NUMBER AND
CUSTOMER_NUMBER.  Saved a lot of time and the psudocode would be kicked around 
by
the design team.

This served two purposes: 1) It forced at least _some_ level of documentation. 
2)
Gave the programmer a head start on the source member.

Although I'm just as guilty as the next person for right side comments, we try 
to
keep them to a minimum.  IMO, if every line needs a comment, there's got to be
something reallllly wrong with the logic <G>

Example:

    C* validate hire date
    C            MOVE    HIREMDY    TESTMDY
    C            EXSR    MDYVFY
    C    MDYOK   IFNE    'Y'
    C            SETON                        70  DSPF ALARM
    C            SETON                        71  DSPF DSPATR(RI PC)
    C            .....
    C            ENDIF

IMO, this is just about all something as simple as this needs. A statement of
purpose and an explanation of indicators set.  I think a newbie would even get 
it
<g>

Another 2 cents in the pot.




Ed.Doxtator@ssa.co.uk wrote:

> >
> >Scott, you are 10000% correct!!!!
> >We try to get our people to write their comments first, then write the
> >code around the comments.
> Exactly right, in my opinion.  It's so much easier to design code if you
> think in a human language and then hang code off that thought.
>
> <<snip>>
>
> Finally, I seem to recall reading that once upon a time, HP used to write
> rough drafts of their manuals, and then started writing code based on the
> manual, rather than the other way around.
>

<<snip>>

+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---