Software Maintainability – Traits of Good Maintainability – Names as Beacons
What makes software maintainable? One of the long accepted beliefs about program comprehension is that as programmers attempt to learn about a program they use what are called “beacons.” Beacons can be anything that a programmer recognizes as a signal of something they’re looking for. Beacons are used for both a) trying comprehend what a program does and b) trying to locate a particular feature in the code.
To make a quick example, if a programmer is tasked with changing a refund calculation, he or she may start by looking for a certain field known to be involved with refunds, such as refund amount.
The use of beacons is one of the most important techniques that programmers use in software maintenance. Anything that can be done to increase or improve their effectiveness should improve the overall maintenance process and make the software more maintainable. So what can be done about this? I believe there are two things that can be done, one when the software is written and the other after the fact.
As software is written the use and enforcement of good names is one of the most fundamental things that can be done to improve the long term maintainability of a system. Naming conventions for fields, files, formats, program, modules, subroutines, procedures and so on all serve to facilitate program comprehension. To be effective the names must meet two criteria:
- They must be recognizably meaningful
- They must be used consistently
For these two criteria to be met one more thing must be met:
- This must be implemented, enforced and followed through!
Many projects start out with naming conventions but how often are they really reviewed and enforced, especially over many years? This is really crucial to long term maintainability.
So what can be done after the fact? You can help programmers know what beacons they can look for! Programmers often approach an unfamiliar program by attempting to map their real world knowledge to the code, so called “top-down” modeling, or “concept assignment.” This is where inexpensive but very effective documentation comes into the picture.
Rather than attempt full-scale technical documentation, which never succeeds of course, a much more cost-effective approach is to produce a small amount of documentation that helps maintenance programmers with two of their most common tasks, 1) concept assignment and 2) feature location.
When the programmer does concept assignment he or she is attempting to map domain knowledge (typically business knowledge) to sections or lines of code. The use of beacons is critical to this task. When performing feature location the task is essentially the same, attempting to map a concept in the form of a software feature or function, to a section or line of code. And again, beacons are central to the task.
A simple document that outlines business processes and software features and then shows common beacons that can be used to identify those processes or features greatly aids programmers as they attempt to map domain knowledge to code. This document can be produced with comparatively minimal effort by employing the particular knowledge of team members in their areas of expertise.
An example of such a document is shown below:
As you can see this documentation consists basically of simply mapping a list of business processes and functions to items that are automatically retrievable from the AS/400. This type of documentation gives big bang for the buck for maintenance work.