Software Code Development

About

This document gives high-level advice for people who develop software for use either internally within a project or for use externally as a project deliverable.

Background

Each computer programming language has its own coding conventions. However there are a number of general points that you can follow to ensure that your code is well organised and can be easily understood by others. These guidelines are not in any way mandatory but attempt to formalise code so that reading, reusing and maintaining code is easier. Most coding standards are arbitrary but adopting some level of consistency will help create better software.

The key point to remember is that good QA practice involves deciding on and recording a number of factors with your programming team before the onset of your project. Having such a record will allow you to be consistent.

Documentation

In order for programmers to use your software it is important that you include clear documentation. This documentation will take the form of internal and external documentation.

• External documentation explains how the software will be used. Internal documentation explains how to implement the code.
• Comments - Comments should be added to your code to explain implementation details of the source code. Avoid adding obvious or lengthy information. Prior to your project you should agree on how frequent comments should be and their location, format and length in the file. These conventions may need to be agreed on for block, single-line and end-of-line comments.
• Readme file - Every software package should contain a readme file describing and the purpose and functionality of the software and information on external dependencies.

Naming Conventions

Naming conventions of files, procedures and variables etc. should be sensible and meaningful and agreed on before the projects starts. Use of capitalisation may vary in different programming languages but it is sensible to avoid names that differ only in case or look very similar. Also avoid names that conflict with standard library names.

Code

There are a number of key points to remember when writing your code:

• Linearity - If using a procedural language make sure your code is linear and starts at the first executable statement and continues to a final return or end of block statement.
• If constructs - Avoid complicated "if" constructs. It is better to use several simpler nested "if" constructs rather than a complicated compound one. Generally keep it simple.
• Layout - Code layout is very important. It should be formatted to provide visual clues to the flow of the implementation. It is useful to agree on factors such as indentation, location of brackets, use of white space and line spacing used before the project starts. For example how long will your lines be? Will you use tabs or spaces?
• External Constants - Define constant values outside of the code as this makes maintenance easier. Changing hard-coded constants can be time-consuming and prone to human error.
• Error Handling - It is also important that you write in some form of error handling into the code.
• Portability - Portable code allows the source file to be compiled with any compiler and executed on any machines and operating system. Creating portable code is fairly complex. It is useful to keep machine dependent and machine independent code in separate files.

Standards

Standards are "documented agreements containing technical specifications or other precise criteria to be used consistently as rules, guidelines, or definitions of characteristics, to ensure that materials, products, processes and services are fit for their purpose" (ISO 1997). The aim of international standards is to encapsulate most appropriate current practice. The International Organization for Standardization (ISO) [1] is the head of all national standardisation bodies. The most relevant ISO standard for software code development is ISO 9000-3: 1997 (QA for the development, supply, installation and maintenance of computer software). For other relevant standards also check the Institute of Electrical and Electronics Engineers [2] and the American National Standards Institute [3].

Project QA

At the start of development it may help to ask your team the following questions:

1. Do you have local guidelines for writing code?
2. Are your software staff aware of the conventions to be used?
3. Do you have procedures in place for use when creating local software?

References

1. The International Organization for Standardization (ISO)
   <http://www.iso.ch/>
2. Institute of Electrical and Electronics Engineers (IEEE)
   <http://www.ieee.org/
3. American National Standards Institute (ANSI)
   <http://www.ansi.org/

Further information on Software QA at Sticky Minds
<http://www.stickyminds.com/>