× The internal search function is temporarily non-functional. The current search engine is no longer viable and we are researching alternatives.
As a stop gap measure, we are using Google's custom search engine service.
If you know of an easy to use, open source, search engine ... please contact support@midrange.com.



<snip>
Generally speaking, and IMO, I don't like to see documentation interrupting
the flow of code.  If some code needs to be documented, the code should be
in a subroutine / subprocedure / service program, and that needs to be
documented.
<snip>

It depends on what you mean by 'interrupting the flow of code.'  I don't like 
programs where every line of code is prefixed with a comment telling me what it 
does.  However, I have followed too many developers that felt if one knew RPG 
they could read the program.  No clues as to what the general idea of the code 
is or why something was done.  The original developer is now gone and no one 
really knows what the program does.  My favorite is systems that use the format 
of 'F' followed by a number for file names and 'D' followed by a number for 
field names.  Not only is there no documentation, but the intent can't be 
intuitively derived from the field names used.

Breaking logic into logical units (subroutine/sub procedure/service program) 
helps a lot.  If the steps required for the task are very lengthy or complex I 
would still put documentation in the code at appropriate points.

Just my $.02.

Rick


As an Amazon Associate we earn from qualifying purchases.

This thread ...


Follow On AppleNews
Return to Archive home page | Return to MIDRANGE.COM home page

This mailing list archive is Copyright 1997-2024 by midrange.com and David Gibbs as a compilation work. Use of the archive is restricted to research of a business or technical nature. Any other uses are prohibited. Full details are available on our policy page. If you have questions about this, please contact [javascript protected email address].

Operating expenses for this site are earned using the Amazon Associate program and Google Adsense.