Programming Standards

*

1 General Programming Standards for All Languages

This section provides a generic outline and general guidelines of what should be used as general programming standards for any program or function in any programming language. Program documentation is a very important part of programming standards. With rapid technical changes and new languages, it is not possible to address standards for all languages used and keep it current. It is possible, however, to provide generic rules for documentation and coding guidelines that are applicable for all languages.

DOCUMENTATION FOR ANY PROGRAM OR FUNCTION:

  1. Name of program or function
  2. Author (optional)
  3. Date created
  4. Input - Description of the input into the program. Include copy members if applicable.
  5. Output - Description of output of program or function if applicable
  6. Update or I-O files or tables - If the program is an update program indicate what data elements and files are updated
  7. Parameters (where applicable)
    If the program or function has parameters, indicate position or layout, valid values, and description of what the parameter means to the program or function.
  8. Program or Function Description
    Describe the purpose of the program or function. It is always helpful to know WHY this program or function was needed or requested by the user.
  9. Program Processing
    Describe any special coding or selection criteria internal to the program. This section may contain a detailed explanation of how the program actually works, what logic is used, unusual programming techniques, etc. It is possible that this section will be lengthy since it should provide the general information needed for someone who is not familiar with the program to be able to read the section and then make any needed changes without too much difficulty.
  10. Called routines or functions (where applicable)
    This section will list any subroutines or functions that the program calls and what needs to be passed or returned.
  11. Return codes (where applicable)
    This section includes standard return codes used as well as any return codes used that are unique to the program or function.
  12. Program modification log or change history:
    This log should have the date, author, and description of the modification. The project request number or bug number for the modification should also be given here.

 

INTERNAL PROGRAMMING GUIDELINES FOR ANY PROGRAM OR FUNCTION:

Always use meaningful variable names. For example, when defining an amount field include "AMT" as part of the name of the field.

Always make your code readable using consistent indentation techniques. For example, always align the If and Else clauses and indent the actions consistently: 

          
                 If 
               Do something 1
               Do something 2
           Else 
              Do something 3
    End-If  
Provide inline program documentation for specific processes or coding techniques. For example: 
    * * * If details are not going to be printed do not 
    * * * read the financial details records.
     
        IF  BD-EXT-IND = SPACES 
             NEXT SENTENCE 
        ELSE 
             PERFORM XXX-READ-FINANCE

This is needed in code where another programmer might not understand what the code is doing and/or why.

 

2 COBOL Standards

2.1 Introduction

The COBOL standards presented in this section were written to aid programmers in writing programs that are easy to understand and maintain. The importance of standards is obvious to anyone who has spent long hours deciphering someone else's code. These standards were developed to provide uniform rules so that other programmers may understand programs more easily, to provide coding techniques that reduce the complexity of programs, and to enhance the self-documenting capabilities of COBOL. These standards are meant to support the concepts of structured programming, including the techniques of modularized code and "top-down" implementation. These techniques alone can go a long way toward improving programs but further benefits can be derived by using them in conjunction with the standards presented here. These benefits include not only improving the future maintainability of a program but also simplifying the initial coding and testing.

An efficient program involves much more than bytes and nanoseconds. The total cost of development and maintenance are key concerns as computer hardware costs continue to decrease. These standards are aimed at promoting more efficient programmers and better quality programs.

 

2.2 IDENTIFICATION DIVISION Standards

Program names identified in the PROGRAM-ID paragraph must be between 8-20 characters long. The ID should some how reflect the programs purpose.  ie.  PRINT-PAYROLL-CHECKS

The AUTHOR paragraph in every program must include the name of the person responsible for writing the program and optionally the name of the person who wrote the program specifications.
RATIONALE: To allow for quicker access to the originators of a program if problems should arise during program development or maintenance. 

The DATE-COMPILED paragraph must be entered with no date - the compiler will automatically fill in this date on the compiled program listing.

The IDENTIFICATION DIVISION must include comment lines that give a description of the program's title and general purpose and any other information which would prove useful to someone maintaining the program (such as required inputs, expected outputs, parameter card formats, error conditions, etc). An example of a possible format follows: 

*TF135A - PROGRAM DOCUMENTATION **********************
*
*  PURPOSE
*    INTERACTIVE UPDATE OF PARKING ZONE MASTER FILE.
*
*  PARAMETER INFORMATION
*    NONE
*
*  FILES
*    ZONE-MASTER   FIXED VSAM, OPENED I-O.  THIS FILE
*                  CONTAINS ZONE ID'S, NUMBER OF 
*                  PARKING SPACES, AND OVERSELL 
*                  PERCENTAGES.
*
*  EXTERNAL SUBROUTINES
*    JULIAN        CONVERTS GREGORIAN DATES TO JULIAN
*
*  DESCRIPTION
*    UPDATE SCREEN IS PRESENTED AT PROGRAM INITIALIZA-
*    TION.  SEE SCREEN DESCRIPTION TF135.1.  CUSTOMER
*    TYPES ID AND PRESSES SEND.  IF THE ID IS NOT ON
*    FILE, CUSTOMER IS PROMPTED TO FILL REMAINING
*    FIELDS FOR NEW ZONE, ELSE SCREEN IS FILLED FROM
*    RECORD AND CUSTOMER IS PROMPTED FOR CHANGES.
*    VALIDATION OCCURS ON SECOND SEND AND ERROR
*    MESSAGES ARE PRESENTED ONE AT A TIME UNTIL ALL
*    ENTRIES ARE VALID.  THE RECORD IS THEN WRITTEN OR
*    REWRITTEN, THE SCREEN CLEARED AND CUSTOMER
*    PROMPTED FOR NEXT ENTRY
*
*    FUNCTION KEYS ARE DEFINED AS FOLLOWS:
*      FUNCTION-1        CLEAR SCREEN AND RESET TO
*                         INITIAL PROMPT.
*
*      FUNCTION-6        RESTORE SCREEN AND PROGRAM TO
*                        STATE OF LAST SEND.
*
*      FUNCTION-5        HALT THE PROGRAM.
*****************************************************

 2.3 DATA DIVISION Standards

File Description (FD)  paragraph must contain the following clauses
       LABEL RECORDS ARE
       RECORDING MODE IS
       RECORD CONTAINS    ---  NB.  this must agree with the FD's 01 Record description
       DATA RECORD IS        ---  NB.  this must agree with the FD's 01 Record description

All data names should describe as accurately as possible the data element being defined.      Data names that are a part of a record description should should not have prefixes or suffixes.   Data name qualification is to be used in all cases.

Data names that are part of WORKING-STORAGE may be constructed using appropriate prefixes/suffixes. ie.  WS-Page-Counter

Any numeric data fields defined in WORKING-STORAGE to be used in arithmetic calculations should be initialized to ZERO and defined a USAGE COMP-3.

 2.4 PROCEDURE DIVISION Standards

In no case is the use of the GO TO verb allowed
RATIONALE: To make a program easier to follow by forcing the program to be organized into functional levels which are completely closed. This type of organization will allow for easier maintenance and documentation.

If AND and OR are used in the same conditional, parentheses should be used to clarify the order of evaluation.  The use of negative logic should be avoided if the condition being tested is unclear to a casual reader.
RATIONALE: To insure that a condition is evaluated as it was intended.

All paragraph names should  describe as accurately as possible the function of that paragraph.
RATIONALE: To improve maintainability by making the reader aware of the task performed by the code.

All paragraph names should be prefixed with a paragraph number consistent with the program's hierarchy chart, preferably three digits, and sequenced by this prefix.
RATIONALE: The numbers reflect the logical order of the paragraphs thereby making them easier to find.

2.5 Appearance Standards

In general, code needs to be as legible as possible. Although not essential, the following methods will help achieve that goal.

Vertically align all major clauses in data descriptions. For example: 

01  MASTER-RECORD.
            02 MR-SOC-SEC-NO               PIC 9(9) COMP-3.
            02 MR-NAME.
               03 MR-LAST-NAME             PIC X(15).
               03 MR-FIRST-NAME            PIC X(10).
            02 MR-BIRTH-DATE               PIC 9(6) COMP-3.
            02 MR-HOME-DEPT                PIC 9(4) COMP-3.

Use blank lines as necessary to improve readability, e. g., separate paragraphs, 01 levels, FD's, etc. with blank lines.

Place division, section and paragraph headers on separate lines.

Do not break words, data names, or numeric literals across lines except for VALUE clauses. (This is permitted only when the VALUE clause is too long to fit on a line by itself.)

Continuation lines must be indented at least two spaces from the beginning of the line being continued.

 

 

Taken from Administrative Information Services Manual

University of North Carolina - Chapel

http://www.ais.unc.edu/stds2/sect_html#6_2