Coding Structure

Rules for Functions

• The function name should help indicate the function purpose.
• Functions should perform only one task.
• Functions should be as short as possible.
• Functions should control changes to internal data by restricting access.
• Each function must have an initial comment. Initial comments in the program should make the algorithm used in the function obvious. The initial comment should explain:
  • What its purpose or use is.
  • What arguments it requires or accepts and what their use is.
  • What value(s) the function returns.
  • What values or parts of the program the function may change.
  • Algorithms used.
  • Conditions which may cause the program to fail.
  • The creator of the function.
  • The date the function was created.
  • The version number of the function.
• Comments in the code must be used frequently to ensure what is happening is easy to understand.
• Compound conditional statements should be limited to avoid confusion.
• When used in functions, the use of { and } should be on their own lines to demark blocks of code.

Rules for variables

• Minimum use of global variables.
• Any modules that use global variables must be identified.
• The input and output variables associated with each function should be identified in comment code at the start of each function.
• All variables should be explicitly declared and given an initial value.
• Hierarchial data structures should be used to keep the data and program structured.
• Variable names should be meaningful.
• Variable names should be in lower case.
• Use simple incrementer variables for loops counters such as the Fortran integer variable names which are i, j, k, l, m, and n.
• In graphics or coordinates, use variables x, y, and z for coordinates. 

Software Code Documentation Requirements

• Program and Technical Documentation
  • Every function or procedure must have a comment header. 
  • Each module shall have a header to describe its function, included procedures or functions, and any additional information about what is needed to use the module.
  • Version numbers for the software and modules shall be maintained and kept on record.
  • Functions must be named in a way that makes sense in describing its use.
  • There must be enough comments in the code so the program can be understood by reading the comments. There must be at least one meaningful comments averaging one for each three lines of code.
  • All file formats must be documented.
  • Variables must have meaningful names excluding variables used for counting or looping.
• User Documentation
  • Documentation must be designed appropriate for the skill level of the user and should not assume technical expertise unless expertise is assured.
  • User documentation must inform users about how to use the program and provide information about available commands and screens. User manuals must be written as simply and direct as possible.
  • A structured training program must be created. 
  
  

   

  General Quality Programming Requirements

• Minimum documentation of code according to the code documentation standard.
• The use of global data must be limited and when used, it must be documented in the function what global data is used. Where the global data is instantiated, it must be documented what functions may modify the data.
• Only one program statement should be put on each line.
• Routines/program code containing functionality which is commonly used such as password reset, login screens, validating and parsing of user input, and display screens should be created and placed in a library where it can be shared with other programmers in the organization. This code should be optimized and designed to be secure. All shared code should be reviewed for flaws before it is shared.
• Programmers are required to use the library of shared code wherever possible to support their project. This will decrease development cost and increase security since the shared code was previously reviewed for flaws. 

Software Code Testing Requirements

Software testing should be performed as software is developed. Different types of software testing is performed depending on the size of the project, the current project phase, and the amount of progress made in the coding process. Developers should document the primary testing methods and test cases used. Types of testing includes:

• Unit testing may also be known as module testing and is used to test small parts of code such as functions and modules. Programmers should test each module to be sure it performs as intended.
• Integration testing - Tests the interfaces between modules.
• System testing - Tests the complete system against the system requirements specification.
• Functional testing - Tests for correct functionality at all levels including modules, classes, system, or interfaces. It tests against the system requirements specification.
• System integration testing is performed when the system needs to interface with other or third party systems. The testing tests against the system requirements specification for interfaces to other systems.
• Performance testing - Tests the service quality and ability of the system to support the required number of connections. Includes stress tests and load tests.
• Installation testing - Determines whether the system can be installed smoothly.
• Security testing - Many people break this into a separate category of testing but this should not be the case since security requirements should be included in the system requirements specification.
• Acceptance testing - Testing by the customer or end user to determine whether the software is acceptable. A test plan is done for this testing and the client will work with developers to create a test plan to test the functionality of the system against the system functional specification. Depending upon the application, acceptance testing may include two additional phases. These phases do not utilize a test plan and basically allow someone to use the system as an end user. These phases are:
  • Alpha testing - Alpha testing would be performed first and is done by a test team, users, or potential customers. The testing is normally done at the site where the developer is.
  • Beta testing - This testing is done after alpha testing and is an early release of software to select people that may be customers or users. The objective is to identify any other problems not previously found and determine whether the software is ready for release.
• Documentation testing - Testing of user documentation to ensure that it is accurate, helpful, and adequate.

Essential testing includes:

• Unit testing during development.
• Integration testing during development and system integration.
• Functional testing during development and system integration.
• System testing.
• System integration testing for systems that interface to other systems and require the interface to those systems to function properly or support a critical part of the business functionality.
• Performance testing for large systems or systems to be used.
• Acceptance testing.

It is management's responsibility to ensure that proper software testing is being done. It cannot be dumped solely into the hands of the developers. The management must be sure the developers have the proper training and tools. The management must also be sure the proper project plan is in place and that the test plan addresses the needs of the project.
A software test plan should be started early in the project life cycle. The types of testing required should be outlined early. Details of testing should be filled in as more information is available including information about the system requirements and system design. For most testing, specific test cases should be created that describe what the tester does, the expected output, and criteria to pass or fail the test.

Testing Requirements

• A test plan must be created. The test plan should be started during the system design phase of the project and refined as the time for final testing draws near. The test plan should:
  • Outline the ways testers will test each module.
  • Identify all software functionality to be tested, and how it will be tested including how to determine whether it passed or failed.
  • Define interface testing by comparing module and system output with expected output when specific input is injected.
  • Create test cases and use them to test business functionality.
  • Define how testing will be done to be sure user manuals are effective.
• The entire system must be tested including user input and output. The test plan should reflect this.
• Every module must be tested. The test plan should reflect this. Each module should be tested as it is coded.
• The system should be tested by programmers in the first phase of testing then the system should be tested by people representing the customer who are not technical.
• There should be acceptance criteria set for the user and documented in the test plan.
• For low level programs such as assembler, the stack and heap usage should be checked and monitored to be sure it does not contain erroneous data and could cause a return to go to the wrong area.
• The test date, test method, and name of the tester should be entered on the module list next to the name of each module.
• Automated testing and code checking tools should be used where possible but those tools should not reduce the need for manual checking and testing.