Dimension: Standards & Interfaces
(Note: This is part of the “Dimensions of SCM Challenge” series.)
For our purposes, there is not much difference between a standard and an interface. Either one can be nearly trivial to support, or can impose enormous costs on the project. Complying with an internal coding standard, an ISO language standard, or a database vendor API can be simplicity itself. Trying to conform to a certain process model, or interface with a complex file format or communications protocol can supply problems for years. Part of this stems from the amount of documentation available for the standard or interface. Abundant documentation usually correlates with a straightforward implementation, especially if the documentation comes from O’Reilly & Associates. When the standard or interface is a moving target you can generally anticipate problems, but anticipating the problems usually helps mitigate them.
Sometimes the interface is all but undocumented. Every significant release of a major web browser is accompanied by a flurry of Internet activity dedicated to researching and understanding all the bugs and quirks in the rendering engine, and a parallel search for ways to uniquely identify the new version from within CSS, within HTML, and using Javascript. If you work for a popular web site or a maker of web design technology, or if your organization specializes in web design, then keeping abreast of these updates is crucial to your business. (If you’ve never dealt with the joys of browser detection, ask a co-worker or friend who has. Once you get them started, the stream of bile and frustration that emerges will curl your hair.)
Working with an undocumented interface that is crucial to your product but totally outside your control is one extreme form of challenge. That particular challenge is usually short-lived, since everyone else in the web industry begins exploring and documenting the browser quirks at the same time. Another kind of challenge happens when you are implementing a standard without any specification of the required outcome. While an open specification works well for requirements, it doesn’t work when different teams interpret the same prose to mean different things in the design. If each side of an interface expects the other side to handle object initialization, for instance, then the first integration test will be short, loud, and exciting.
One key ‘gotcha’ to beware of when dealing with a technical standard or interface is the need to explore these standards very early in the process. Even when you are ‘assured’ of documentation or technical details, there are often subtle dependencies on the ‘usual’ values or the order of certain items. For instance, a generic “set parameter” interface may actually require that parameter A always be set before parameter B. If your project doesn’t control both sides of the interface, you should allocate time early on to mapping out the context and expectations.
Interface Management is a defined part of configuration management. Sadly, few software shops have much (if any) experience formally managing interfaces. There is a technique, Formal Interfaces & Standards, that uses the constraints and rigidity of interfaces as a strength rather than dealing with them as a challenge. This is a question of choice—the technique relies on using interfaces that you choose to put in place, rather than externally-imposed constraints. In fact, once you have agreed to use a standard, it doesn’t matter how it came to be. Having voluntarily agreed to the constraints may make the situation more palatable, but the concrete challenges will be the ones listed above.
The lifespan of a standard or interface is one of the most important factors in determining the inconvenience it will cause. A long-lasting standard or interface will generally be better documented, more flexible, and can be incorporated into the requirements, architecture, and design of the product. It is unlikely to change at all, but if it does change it will likely be a minor modification or update. A short-term interface or standard will generally be seen only at the design phase and after. It may be modified, updated, or it may disappear entirely between one release and the next.
For example, a “supported operating systems” list is a long term constraint, with updates as new OS versions are released, and a gradual phasing out of old versions. (Current-day Windows applications support surprisingly old versions of Windows, going as far back as 98 or ME.)
Another example: the decision to support a particular version or release of Oracle might qualify as either a long- or short-term constraint. If the Oracle software is being bundled with the product, or is expected to be installed on a dedicated server for the product, then the required Oracle version can be changed in lockstep with new product releases (usually with a small fudge-factor for upgrades). But if the Oracle installation is expected to be part of a customer’s existing infrastructure then the range of versions supported will be much wider, and testing will need to be much more thorough.
One last example: if an interface is completely internal to the product—a gateway between two modules, or a file format—it is likely to be entirely under control of the respective development groups, and so can be changed from version to version. In this case, the only limiting factor is the agreement of the various teams that use the interface. This is no small thing, since some of the other dimensions of challenge can rear their ugly heads at this point. Using Formal Interfaces & Standards is a good way to isolate development teams that are divided by geography, language, culture, or politics. But using the technique transfers part of the challenge directly from those dimensions to this one—a geography or culture challenge is transformed into a standards conformance challenge.
Using interfaces is a boolean proposition: either the system correctly uses the interface, or it does not. (Which is not to suggest that all interfaces are simple!) This is normally determined as part of system testing. Standards are less sanguine. Some standards, like programming language syntax, can be verified mechanically. Others have to be enforced or checked using a higher level process. In some cases, like with a process standard, the higher level process is necessary just to implement the standard, and so an even higher level process is required for checking. Checking for conformance can sometimes be implemented either manually or with an automated process. The choice between automation and manual effort may be a property of the standard, or it may be a cost-based or effort-based decision. Opting to spend thousands of man-hours a few at a time in a manual process over months or years instead of spending tens or hundreds of man-hours automating a process is a management decision—frequently a surprising one.
The decomposition-based construction techniques (Component-based Development, Service-oriented Architecture, and Software Assembly) are all potentially useful, provided that the decomposition aligns with the interfaces and that the interfaces are at roughly the same level as the granularity of the decompositions. It makes no sense to try to break up a complex library in order to align it with a special memory allocation package. When dealing with standards, rather than interfaces, decomposition won’t provide any direct benefits. In this case, Software Product Lines might be useful if the standard can be viewed as a feature—that is, if the standard is not an all-or-nothing proposition but instead constrains a subset of the product, or can be presented as an optional element. Many programs offer installation options to select one or more languages or character sets for the user interface or for program data. If conformance to an accessibility standard were an installation option, SPL would be a useful approach. Similarly, if the standard in question is a technical standard like support for a particular file format or graphics engine then SPL may be a good fit. The Microsoft Office™ suite installation process used to offer file format translators for a slew of competing products as optional packages. An organization converting from another word processor or spreadsheet package could install the readers for those file formats, while other customers could save the disk space.
Of the organizational techniques, System Architect has relatively little to offer. Using a Change Control Board can be an effective way to manage changes to an interface or standard, since the board will likely be small enough to work effectively together but diverse enough to consider all the likely impacts of a change. The makeup of the board will dictate its effectiveness dealing with interfaces or standards. A board that is represented along political/organizational lines (1 seat for QA, 1 seat for IT, 1 seat for Development, etc.) will handle process standards well, but will likely not do well for technical interfaces. Conversely, a board broken down along functional lines (1 seat for electrical, 1 seat for sensors, 1 seat for control systems) will do well managing technical interfaces but may not fully grasp the nuances of a process standard. Having a Subject Matter Expert can be an effective way to deal with a standard or interface, provided the SME is expert in the standard. When the interface or standard is key to the project, a SME is nearly always a good solution.
Technical standards and interfaces generally don’t interact with the work flow techniques. Process standards are another story. Project Baseline is likely to be the SCM technique envisioned by the authors, designers, and implementers of nearly all process standards. As a result, using Project Baseline is likely to minimize the problems encountered when first adopting a process standard. Problematically, not all projects can use Project Baseline, especially not with recent process standards like ITIL. Longacre Deployment Management™ bridges between the Project Baseline and ITIL styles, and can provide enough of an “adapter” to help complex projects conform to common, consistent standards.
The codevelopment techniques can be useful with technical standards (as opposed to process standards) and with most interfaces. Independent Development Paths created at the right level can permit a group of developers to make changes to an interface without blowing up the development environment for the rest of the team. Likewise, Distributed CM lets separate teams work separately. If the organizational structure is aligned with the interface structure, this will help keep both sides of the interface(s) separate, but bring their work together for integration in a controlled manner. Finally there is Formal Interfaces & Standards. Recommending this as a response to Interface challenges seems a bit of a bromide—“when life gives you interfaces, make interface-ade”—but it works. For technical standards, fighting one interface problem with another interface is a straightforward Facade pattern, or an Abstraction Layer.
Standards conformance is a ceremonious activitity, and all of the ceremonious techniques are potentially useful. Requirements Management can help with high-level technical standards, and with low- and mid-level process standards. (Low-level technical standards tend to disappear behind a single requirement, which isn’t very useful. And high-level process standards usually control the process of implementing the requirements—they are too high level for requirements to be useful.) Automated Enforcement of Standards is pretty much a no-brainer, provided the standards are amenable to being enforced automatically. Treating interfaces separately, and using a tool like IDL or rpcgen to manage them fits into this category. AES is not restricted only to process standards. Lastly, Gated Workflow can help with process standards and human-centric technical standards by forcing the standards verification to take place early in the change life cycle. As an example, certain software controlling the administration of drugs is required by the FDA to be peer reviewed whenever a change is made. Inserting this peer review sign-off into the change request work flow is an effective solution to the constraint.
(This was published as part of “Dimensions of SCM Challenge #2: Standards and Interfaces & Requirements or Business Demands” in CM Journal, Vol. 6, No. 3, March 2008.)