[GNU-COBOL] Updated Std & prac

["Chad Slaughter" <slaught@umr.edu>]

hello,
I've tried to get all the comments into the new std & practices docuemnt.
I fi missed any let me know.


The Cobol Project Standards and Practices.

1) All code will be Readable and Maintainable.
    This means using meaningful variable names and writing code that
    should leave no doubt as to is purpose, return value, or meaning.

2) The project will follow the Extreme programming methodology.
   see URLs below for more in depth info.

3) All code will compile under the GNU cc compiler with no warnings or
   errors using the following flags: -Wall 
   The following flags are HIGHLY suggested, if you use them and get a
   warning a technical justification will be required.
   Extras: -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations

4) Any code that uses heap memory will need to be linked against a memory
   leak detection package(such as dmalloc) and run with no leaks.
   *Note: a usage guide is being written.

5) All code will have comprehensive unit tests written for it.
   All tests written will be come part of the codes complete regression
   test suite. All tests will pass all unit tests, BEFORE it is allowed
   in CVS. 
   the stuff you learn in basic programming courses. 
   See the Book references, Writing Solid code for more in depth stuff.
   Testing deals with boundary conditions, checking of valid input/output,
   check of error conditions, etc.
  
6) All C code will be ANSI & Posix compliant at a minimum. 
   Except no using trigraphs. GNU extensions are acceptable if needed.
   All Java & NetRexx code will be Java 1.1 compliant.

7) Naming for all externally visible entities in runtime and outputted
   code will be prefixed With "Cobol<libraryname>__" 
   Note: That is Two(2) underscores after the prefix.

8) The GNU coding standard is a subset and only a minimum standard.
   There is no conflict between it and the first rule.

a) Std page 18 - Code formatting beyond 80 columns and needs to be "folded" 
   Code that is folded across multiply lines b/c it goes beyond 80 columns
   as a high likely hood of needing to be refactored.
   http://www.armaties.com/Practices/PracCodeFormat.html
   *Note: I will expand on this as time goes by.

b) Std page 20 - All pointer declaration need to be on a line by them self.
   Ex:  char * one, *two;   /* this is a no-no */
        /* better way */
        char *one;
        char *two;
c) Std page 21 -  variable names.
   It suggests the use of underscores as separators in C. BUT
   Variable names can use mixed case, instead of underscores.
   Functions and types can be mixed case also. This is preferred, but if you
   follow the gnu standard it is acceptable.


URLS for readability, maintainable code & other standards and practices.
GNU Standard: http://www.gnu.org/prep/standards_toc.html
Extreme Programming: 
  http://www.armaties.com/Practices/PracLeadin.htm
  http://c2.com/cgi/wiki?ExtremeProgramming
  http://c2.com/cgi/wiki?ExtremeProgrammingRoadmap
Dmalloc:

Books to reference for readable & maintainable code.
   The C programming Language 2nd edition, K&R
   Writing Solid Code, Maguire.
   Large Scale C++ Software Design, Lakos
   POSIX Programmer's Guide, Lewine



-- 
Chad Slaughter  -- slaught at umr.edu
<PGP public key available upon request>

--
This message was sent through the gnu-cobol mailing list.  To remove yourself
from this mailing list, send a message to gnu-cobol@acm.cs.umr.edu with the
words "unsubscribe gnu-cobol" in the message body.  For more information on
the GNU COBOL project, send mail to gnu-cobol-owner@acm.cs.umr.edu.