Easing the pain of software maintenace

To get the best possible value, proper documentation is essential; not only for the engineers who already work on the code – for example, to find out how changes they plan might affect the existing software – but also for new recruits, who will need to learn the architecture and understand how modules interact. The existence of documentation generation tools demonstrates how important this area is. These work largely by extracting specially formatted comments and software contracts, where available, from the source code, then creating reference manuals in text or html files. These tools can offer effective ways to document APIs and detailed design, as the commentary should be written alongside the code – giving it the best chance of being kept up to date when the code is changed. Many software developers will be familiar with these tools, which require little extra effort to incorporate into source code as it is written. An important factor is that coding standards are included to ensure these tools are used consistently; it should not be left to the whim of the developer. Such standards can apply across the organisation or on a per project basis. However, in the real world, when deadlines loom or get brought forward, software changes are made rapidly under time pressure and budgets are tight. Ensuring that software documentation exists and is up to date is often seen as a luxury. While automated tools are good at documenting detailed aspects of source code, they become progressively less useful for the higher level system designs and architectures. There is a need for ways to document aspects of the design that are not always best described in the source code itself – for example, constraints imposed by the run time environment, other designs that were considered, why they were not implemented and how modules within the system interact. The need for reliable and flexible ways to document software outside of the source code itself is well known and has many potential solutions. Some involve the use of sophisticated tools in the design phase of waterfall or V development models (see fig 1) and for reverse engineering design information from existing source code. Investing in such tools simply to document an existing code base can be a forbidding and risky proposition. A less expensive and more flexible approach is to use a collaboration tool, such as a wiki, to provide a framework for software documentation. This is appealing, not only because of its relatively low cost, but also because the approach is familiar to many engineers and requires little effort to learn. It's possible to 'start small' with a wiki and discover whether or not it's working for you. A wiki will allow you to create a documentation framework based on common, freely available tools (such as web browser, wiki software, simple mark up language and diagramming facilities). By starting with this uncluttered, but robust, backbone, you can create a simple process which will allow for future extensions to the documentation and, eventually, have every document up to date. Where do I start? Documenting an existing software system may seem a daunting prospect, but stick with it – it will be worth it! The key is to tackle it in manageable chunks, reviewing and fine tuning the framework at each stage until you have something which is working effectively. The first, and most important, step is to build a clear outline of the software architecture; this should be used as a framework for designing the way in which the wiki will be laid out. This is typically carried out and agreed by senior team members, who should have a view of the architecture as a whole. Pebble Bay's experience suggests first documenting a fairly self contained module. As far as possible, it should have characteristics typical of the whole software as part of the framework development process. As the framework develops, you should be able to see what is working and what needs to be revisited. Often, there will be several aspects, or 'views', that your documentation framework should reflect. For example, apart from a top down hierarchical view – usually the best way for new users to discover how modules interact – it may be important to have a way to collate and view information about the process or threading model. You can think of these as 'vertical slices' through the top down design. By developing an initial framework prototype and populating it with real information extracted from the software and existing, but out of date, documentation, it is clearer what the key views need to be. These may include performance constraints, design patterns, execution environment and architecture, to name a few. The framework will then allow users to navigate the wiki based on the software architecture itself; in a hierarchical way, or by choosing one of the views and looking for information that fits within the view. It can also be useful to identify external tools and plug ins for the wiki. For example, a plug that creates template pages with self contained help could save hours of engineering time when creating new documentation pages. And a plug in that could be used to create and edit diagrams, such as UML class or sequence diagrams embedded in the wiki pages, could bring clarity to more complex architectures. This collaborative framework will encourage ownership for the software documentation to be taken by the software team as whole, which will result in documents being kept up to date. A recent case study An industry leading communications company has a code base of current software which has evolved over 10 years from the initial design to incorporate support for new functionality and changes in hardware and many different hardware variants. It has a core engineering team with senior members who understand the software architecture well and with responsibility for different software components spread throughout the team. However, because of a number of factors, including the size of the code base – some 500,000 lines of C code – and the fact that it has to operate in severely resource constrained environments, the software is not easy to comprehend and navigate. While the software is well documented at the source code level, the architecture and design documentation has lagged changes to the code base. Once the company decided to use a wiki, it allowed engineers to update the documentation as they worked on the software, lowering the psychological barrier to keeping the documentation accurate. The wiki provides sufficient structure to organise the documentation in a hierarchical fashion to mirror the overall modular design of the software. The framework has proven invaluable in making it easy for the engineers to update and maintain the architecture documentation and the organisation now has a resource that many teams at different sites can use and benefit from. John Efstathiades is technical director of Pebble Bay Consulting.