Code Maintainability

2.2 Ensure that code is well laid out to aid maintainability

Is is generally good programming practice to lay a computer program out in a logical order. This involves deciding on and following a coding standard. It may be that the organisation for which the software is being developed has its own standards. However, there are a few general standards that can be applied to all programming languages.

1. Keep the data section together and well commented. This is where all of the variables and constants that are going to be used within the program will be declared and initialised.

2. Keep all of the functions (modules) together and organised in such a way that they can be easily found.

3. Add reference details to functions and other parts of the main code. These reference details can be found in other programming design documentation.

One way to follow a coding layout standard is to mirror the layout of any of the graphical design techniques and algorithms used. Good programmers spend some time on the layout of their code and then proceed to code one module at a time. This makes use of Test Stubs. These are areas of code that have no function other than to be place holders for code and to display information regarding the awaited code.

Once you start to translate a design into programming code it is a good idea to make sure that the code is laid out in a structured and readable manner. Typically, this will involve adhering to the documentation standards of the organization where the programming is being carried out. Most organisations will have their own standards.

It may prove useful in large programs to look at the use of maintaining a hierarchical reference numbering system for the code, for example, 0, 1, 2, 3, 1.1, 1.2, 1.3, 2.1, 2.2, etc. This will allow the code to be laid out in such a way as to support the visual design of the code, for example, the Structure Chart.

When you are entering a program into an editor for the first time it is a good idea to program in a manner that is known as defensive programming. That is, you are going to code in such a way as to minimize later errors. One way to code defensively is to use strict and consistent indentation along with comments to make the structure and the meaning of the code as clear as possible.

If you have to type in a bracket or some other symbol that must have a matching symbol to close it, then it is better to enter the two symbols and associated comments at the same time, rather than after all of the other lines of an algorithm have been translated and typed in.

It is recommended that a program is entered and tested one module at a time with a general rule of thumb for the modules that should be developed first being the output modules because even although they will not output the final information they can be used as one test to see what the program is producing from an early stage. The next modules that should be coded are the input modules until finally the processing modules. The reason for leaving the processing modules to the end is that the coding of these may turn out to be the most fraught with problems and that coding the output and inputs first may give more time for the programmer to think about different solutions for the processing part of the program.

Next: Internal Documentation