I can't say that I disagree. However, I have seen the opposite problem;
i.e., the program logic changes, but the documentation isn't changed. More
than once I have tried to make sense of a program in which I could see that
it was doing one thing, but the documentation said something different.
Jerry C. Adams
IBM i Programmer/Analyst
The doctors X-rayed my head and found nothing. - Dizzy Dean
--
A&K Wholesale
Murfreesboro, TN
615-867-5070
-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx]
On Behalf Of Charles Sallee
Sent: Monday, March 26, 2012 9:28 AM
To: rpg400-l@xxxxxxxxxxxx
Subject: FW: commenting sub procedures
By comparison, in many of those cases, the procedure itself will have
minimal documentation, since any developer who has to maintain it should
know what they're >doing before they start messing with the code.
FWIW this is a dangerous attitude, in my opinion anyway. It presumes
someone thinks like you do and can understand your logic quickly. This may
not be true. Comments in the code, even to the point of pseudo-code, can be
of great benefit to those having to understand why you did something the way
you did.
I concur. It has been my experience that the only documentation that really
survives (and is meaningful) is what the developer puts in the code.
Written documentation disappears and/or is very seldom passed along or
looked at. If you can help the next developer understand what you are
doing, you can cut his work in half and improve the results of his work
also.
The same goes for user documentation, if it not part of the software, the
user will most likely not see it. User documentation needs to be written
into the software and help screens.
Thanks, Chuck
--
This is the RPG programming on the IBM i / System i (RPG400-L) mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx To subscribe, unsubscribe, or
change list options,
visit:
http://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives at
http://archive.midrange.com/rpg400-l.
midrange.com
