Re: Line-by-line commenting in source code -- MIDRANGE-L

Here, there are comments like 'Display Prompt' right before the statement
EXFMT Prompt. If you don't know that EXFMT Prompt is going to be displaying
a prompt screen, you have no business editing the code.

 What bothers me is that the code is polluted with stuff like that, but
there are complex expressions with non descriptive field names that are not
documented. I've developed a standard for documentation here after working
on the code that was here before I arrived. We document business rules,
complex expressions, what sub-procedures do and what they return as well in
which service program they reside, and other USEFUL stuff. If we have a
programmer here that doesn't do it that way, he/she won't be back. When we
get a contract programmer or a consultant, the first thing they get is the
documentation standard.

We don't have a coding standard per se but the documentation is important.

Thanks,

Mark

Mark D. Walter
Senior Programmer/Analyst
CCX, Inc.
mwalter@xxxxxxxxxx
http://www.ccxinc.com


|---------+------------------------------->
|         |           "David A Parnin"    |
|         |           <daparnin@cooperstan|
|         |           dard.com>           |
|         |           Sent by:            |
|         |           midrange-l-bounces@m|
|         |           idrange.com         |
|         |                               |
|         |                               |
|         |           02/26/2004 08:51 AM |
|         |           Please respond to   |
|         |           Midrange Systems    |
|         |           Technical Discussion|
|         |                               |
|---------+------------------------------->
  
>------------------------------------------------------------------------------------------------------------------------------|
  |                                                                             
                                                 |
  |       To:       midrange-l@xxxxxxxxxxxx                                     
                                                 |
  |       cc:                                                                   
                                                 |
  |       Subject:  Re: Line-by-line commenting in source code                  
                                                 |
  
>------------------------------------------------------------------------------------------------------------------------------|





James,

No, it's just you.  :)  Actually, long ago I got in the habit of putting
"That's all folks!" at the end of the program such as just before setting
on LR in RPG.  Other than that, no.  I have seen verbose comments where the
original coder when off on a rant about this or that.  Still, a lot of
times comments are like road signs in the desert--few and far between.

<soapbox>
As far as commenting in general I've noticed that far too many commercial
and even a good number of in-house programs are sparse on comments as to
what (and why) the code is doing.  Heck, I even forget what my own code
does sometimes unless I write more than a two or three word description.
Why not do a sentence or two if warranted?  In the grand scheme of things
they don't take up *that* much space.
</soapbox>

Dave Parnin
Nishikawa Standard Company
Topeka, IN  46571
daparnin@xxxxxxxxxxxxxxxxxx





                      James H H Lampert

                      <jamesl@xxxxxxxxx        To:
midrange-l@xxxxxxxxxxxx@SMTP@CTB
                      om>                      cc:

                                               Subject:  Line-by-line
commenting in source code
                      02/25/2004 07:15

                      PM

                      Please respond to

                      Midrange Systems

                      Technical

                      Discussion

                      <midrange-l@midra

                      nge.com>






Am I the only one who, when line-by-line comments (either RPG or MI) start
to form a sentence with a few words on each line, finishes out the series
of comments with a line that simply says, "Burma Shave"?

Does anybody else have quirky little bits of comic relief in the source
code? Like my tendency to put allusions to Jadzia or Ezri Dax into the
comments on code that deals with JOINED files? Or a colleague, who was a
real fan of "Buffy the Vampire Slayer," naming some input or output buffer
"BUFFY"?

--
JHHL


_______________________________________________
This is the Midrange Systems Technical Discussion (MIDRANGE-L) mailing list
To post a message email: MIDRANGE-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/midrange-l
or email: MIDRANGE-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/midrange-l.




_______________________________________________
This is the Midrange Systems Technical Discussion (MIDRANGE-L) mailing list
To post a message email: MIDRANGE-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/midrange-l
or email: MIDRANGE-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/midrange-l.