10.2 Extendability Requirement Pattern

10.2 Extendability Requirement Pattern

Basic Details

Related patterns:	Inter-system interface, documentation
Anticipated frequency:	For most systems no more than two requirements; for complex systems fewer than 10 requirements
Pattern classifications:	None

Applicability

Use the extendability requirement pattern to mandate that a specific aspect of the system be built to make it easy to extend by "plugging in" extra software. In particular, use it in situations where there are (or might be in the future) several different ways of doing things and we want to be able to add more without major disruption.

Do not use the extendability requirement pattern for alternatives that cannot be achieved by slotting in extra software. Common examples are differences achievable solely by configuration, including some multinesses (such as multi-lingual and multi-currency), and variations that affect the system as a whole, such as being able to run on multiple named operating systems (you can't just "plug in" the ability to run on Unix).

Discussion

An extendability requirement acts as a way to tell developers to build a particular part of the system in a flexible manner so that we can extend it by simply slotting in new software without revamping the underlying architecture each time. Some kinds of flexibility aren't amenable to being treated in this way-including anything that can be regarded as a multiness (according the multiness requirement pattern) and anything that can't be achieved simply by adding software to support it. If you have a fixed list of alternatives that cannot grow, you don't need extendability but it can still be good practice to apply it, because extendability promotes modularity: it's a subtle way of encouraging good design in one area. In any case, it's rash to assume something will never, ever change.

This requirement pattern calls a piece of software that is plugged in a driver, as in a device driver or a printer driver. This term is used only to make this discussion easier to read; requirements themselves don't need to use it. An extendability requirement is invariably followed by at least one requirement for a driver, because without it the ability to extend serves no immediate purpose.

An extendability requirement usually sits amid a sequence of requirements: first a requirement that defines an aspect of the system; second the requirement that this aspect be extendable; and finally one or more requirements for drivers and possibly other requirements (all of which are covered in the "Extra Requirements" section later in this pattern). The extendability of an aspect of the system can be combined with its definition, but separating them gives the need for extendability added weight and allows it to be given a different priority. This sequence is shown in Figure 10-2.

Figure 10-2: The sequence of extendability-related requirements

Here are a few typical examples of extendability:

• Available payment methods. (See the example requirement later in this pattern.)

• Supported file formats. Regard each circumstance in which files are accessed as a separate kind of extendability. For example, if one part of a system reads graphics files and another part reads text files, treat them separately. Also treat input and output as distinct.

• External systems to interface to-provided they all play the same role.

• Types of notification methods. (See the example requirement in this pattern and the driver requirements in the "Extra Requirements" section.)

• Types of devices to control-for example, printers or EFTPOS terminals.

• Supported communication protocols.

• Allowed encryption algorithms. Don't mix fundamentally different types of encryption though: a public key algorithm and a symmetric algorithm aren't interchangeable.

Extendability is much more important and valuable when building a software product to be sold to multiple organizations than when building for one organization only. It makes it easier to tailor each installation, without affecting the core product.

Sometimes building in the ability to easily extend in a certain way turns out to be harder than it appeared at requirements time. For example, the things on your list of alternatives might have less in common than they appear; they might vary a lot more. This might not become clear until design time. So there are limits to how much we can expect from extendability.

Content

An extendability requirement needs to cover:

1. The aspect of the system that is to be extendable Which can be expressed in terms of the type of driver to slot in.

2. Ease of extendability How easy should it be to slot in a new driver? Usually it's best to simply insist that a new driver be added without software changes to the core system. This is equivalent to being able to plug a new electrical device into the main grid's power without having to modifying the socket you plug it in. Occasionally you might need to demand more-some kind of plug-and-play capability, perhaps-so that a new driver can be added without shutting down the system.

3. Configuration details In addition to its software, configuration information is needed for each driver so that the system knows it's there and how to call it. This too is largely a matter for the developers to sort out. The requirements need to worry only about anything that's visible to users, such as the name by which it's presented to them. If you want anything else to be visible-such as a help page-then say so.

Perhaps surprisingly, extendability requirements tend to be remarkably straightforward, simple even. The main reason is that they should ignore technical details. They merely need to state what we want; how it's achieved is the developers' responsibility.

Template(s)

Open table as spreadsheet

Summary	Definition
«System aspect» extendable	It shall be possible to extend the «System aspect» by developing and "plugging in" an extra software module. The introduction of any such module shall not require fundamental changes to the core software of the system to allow its introduction. «Ease of extendability». [«Configuration details».]
«Subcomponent type» pluggable	It shall be possible to add a new «Subcomponent type» by developing and "plugging in" the software necessary to support it. A new «Subcomponent type» shall not require fundamental changes to the core software of the system to allow its introduction. «Ease of extendability». [«Configuration details».]

Example(s)

Open table as spreadsheet

Summary	Definition
Notification methods pluggable	It shall be possible to add a new method for notifying users by developing and "plugging in" the software necessary to support that method. A new notification method shall not require changes to the core software of the system to allow its introduction.
Payment methods pluggable	It shall be possible to add a new method by which customers can pay by developing and "plugging in" the software necessary to support that method. A new payment method shall not require changes to the core software of the system to allow its introduction.

Extra Requirements

An extendability requirement can be followed by several extra requirements. There is usually at least one of first type from the list that follows; the others are topics you should give at least cursory thought to, although they're not often relevant:

1. A type of driver, one requirement for each.

2. Installation, to specify how easy it must be to install and configure a driver.

3. Third-party driver development, if people outside your development team will need to develop and test drivers.

Each of these is discussed in its own subsection that follows.

You might encounter extra dilemmas when specifying some types of drivers, but most turn out to be due to the nature of the driver rather than making this area extendable. Be alert to the distinction. Here are a few such situations:

4. Driver security Convenient extendability can open security holes: making it easy to slot in new software makes it easy to slot in malicious software. If this is a concern, take steps to guard against it. Give driver security particular thought if third parties will develop drivers. (See the "Third-Party Driver Development Requirements" subsection later in this pattern).

5. Switching from using one driver to another For example, if we can plug in encryption algorithms, we could decide to stop using one and start using another. This might be a hard thing to do (if we have to re-encrypt anything encrypted using the old algorithm), but any difficulty has nothing to do with extendability.

6. Catering for multiple different versions of a driver Treat each version as a separate driver, but define the configuration information such that it recognizes the relationship between the two and perhaps their order (that is, which comes first). How to decide which version to use is nothing to do with extendability; neither are the complications you might face in gradually moving from an old version to a new version or in dropping an old version as soon as it's no longer needed. But these issues must be confronted.

7. Distinguishing between multiple different drivers and multiple instances of the same driver Some drivers need instances to be created, and some drivers don't. For example, for printers you need a driver for each type, and then each physical printer is an instance (and you can have two printers that use the same driver). For output file formats you don't need to worry about this: once you have a driver for a particular format, you simply use it whenever you like.

Driver Type Requirements

Having a separate requirement for each type of unit to plug in lets us prioritize them individually and gives us space to say whatever's useful about each one. It also reduces the temptation to gloss over each one, which a simple list within another requirement encourages-and it denies us the opportunity to end such a list with an insidiously nasty and unacceptable "etc."

A requirement for a type of driver needs to contain these items:

1. Driver description, of what is to be slotted in, to whatever level of detail is needed-although a brief summary often suffices. Mention any special characteristics you think are relevant, especially things that might affect its complexity (and, consequently, any estimate of how much it will cost to implement). Say enough to make clear what needs to be done. For example, for a file format, state which version and give the location of the standard that defines it. For a payment method, don't just say "credit card"; consider the types you need to support and the financial institution(s) you need to clear transactions with.

2. The system aspect to which the driver relates-or the type of driver being plugged in-as per the parent extendability requirement. You can often express this in passing. You might think this is obvious from the context of the requirement (that is, because it follows its parent requirement), but it needs to be clear when read in isolation.

3. Special information (if any) needed by the driver each time it is invoked. For example, pager notification needs a pager number, email notification needs an email address, and credit card payment needs credit card details. Say where this information comes from.

   You might also need to specify special configuration details for a specific driver.

4. Responsibility for underlying infrastructure-a description of who is responsible for specifying and implementing it. If a driver is neatly self-contained (such as one for a file format), no more needs to be said. But a driver often involves considerable behind-the-scenes infrastructure functionality-for example, a credit card payment mechanism or pager notification service-functionality that must be properly specified and implemented. Who's responsible? Is it within the scope of this system? Is the necessary infrastructure already in place? You must answer these questions. If you're going to leave this until later, you must make that clear: make it obvious that specification work is incomplete. The easiest answer is to say it's outside the scope and that the necessary infrastructure must be properly specified before this requirement can be satisfied.

These requirements tend to be as straightforward as extendability requirements (although the responsibility part can be awkward to express and can end up looking like picky legalese). It's easy to see why: we're interested in only the extendability aspect here; everything needed to deliver it is omitted. That's why further requirements must be written-somewhere-if some kind of supporting infrastructure is needed. Implementing each infrastructure deserves to be a project (or subproject) in its own right, or it might not receive the attention it deserves. In any situation where a large amount of work hides behind one innocuous requirement, it's likely to be given an inadequate budget and to be rushed. Developers are apt to dash out and find the first open source product they lay their eyes on. An infrastructure could be used for other purposes, too.

Any driver whose real work is done by a separate component (such as a third-party product or an external system) acts as an adapter. See the inter-system interface requirement pattern's "Interface Adapters" sidebar (in Chapter 5, "Fundamental Requirement Patterns") for a description of what adapters are all about.

Here are a few example follow-on requirements that specify drivers for notification methods (and notice the stressing of the infrastructures that are needed):

Open table as spreadsheet

Summary	Definition
Notify via system message inquiry	It shall be possible to notify users of relevant events via the system message inquiry (as specified in requirement XR8.2), if they have it running.
Notify via email	It shall be possible to notify users of relevant events via email. To notify a user, an email address must have been entered for them. This requirement assumes the presence of an infrastructure for sending emails. Specifying and implementing such an infrastructure is outside the scope of this system, but must be done in order to satisfy this requirement.
Notify via mobile phone instant message	It shall be possible to notify users of relevant events via instant messages to a mobile phone. To notify a user, a mobile phone number must have been set for them. This requirement assumes the presence of an instant messaging infrastructure. Specifying and implementing such an infrastructure is outside the scope of this system, but must be done in order to satisfy this requirement.
Notify via pager	It shall be possible to notify users of relevant events via pager. To notify a user, a pager number must have been set for them. This requirement assumes the presence of an infrastructure for sending messages to a pager service. Specifying and implementing such an infrastructure is outside the scope of this system but must be done in order to satisfy this requirement.

Driver Installation Requirements

Installing a driver takes two steps, both of which can be influenced by requirements if you want to:

1. Install its software If nothing is said about this, it's reasonable for everyone to assume that driver software will be installed in exactly the same way as any other software. If it needs to be easier (and, technology permitting, it can be made easier), add requirements to say so. The technology might let you install driver software while the system is running-but press for that only if there's a sound business need behind it.

2. Configure it Each type of driver needs a function for configuring it. The presence of such a function is often left unstated, but it's a good idea to specify it explicitly.

   A driver's configuration can also control its availability-that is, whether it's "switched on" or not. You could write a requirement asking for the ability to install a driver but not make it available immediately.

Here are a couple of example requirements related to the installation and control of drivers:

Open table as spreadsheet

Summary	Definition
Notification method maintenance	There shall be a maintenance function to allow the entry of details about a new notification method and the editing of existing methods.
Notification method availability	It shall be possible to specify for each notification method whether it is available for use or not. When a new notification method is added, it shall by default be unavailable. It shall be possible to change this value by using the notification method maintenance function.

Third-Party Driver Development Requirements

Is anyone outside your development team likely to be developing software to slot in? If so, they'll need to know how to do it. At the very least we have to publish a definition of the interface they must build to, but it's better to insist that a "Driver Developer's Guide" be written for this type of driver. Here's an example of such a requirement:

Open table as spreadsheet

Summary	Definition
Notification method development guide	A development guide shall be written containing sufficient information to allow a competent software engineer with suitable skills to develop a notification method driver.

Requirements very similar to this are also used to allow third-party development of inter-system interfaces, as described in the inter-system interface requirement pattern in Chapter 5. See also the documentation requirement pattern, also in Chapter 5, for more about what to say.

You also need to be alert to the security implications of adding software written by a third party into your system. How much do you trust them? What steps can you take to protect your system? Here are a few suggestions [which indicate, within square brackets, who the work is to be done by]:

1. Insist that the source code be supplied for all driver software written by third parties. Also insist on adequate documentation, including commenting of the source code. [To be done by the third party]

2. Examine the source code for suspicious activities. [To be done by a suitable member of the development team or the testing team]

3. Compile the source code, and install that object code (rather than object code supplied by the third party). If you've checked the source code, that'd be a waste of time if the supplied compiled code is different. [To be done by a member of the development team or a system administrator]

4. Test the driver thoroughly. [To be done by the development team and/or the testing team]

Requirements aren't necessarily the best place to state these things, but you could write a requirement saying that precautions along these lines be taken.

Considerations for Development

An extendability requirement is in effect an instruction to the development team saying, "Build this part in a flexible way; don't hard-code it." Development depends on the type of extendability and the technology being used, so little more can be said here. A few things to bear in mind are as follows:

1. Configuration for drivers Every type of driver needs its own configuration. What does it need to contain? Possibilities include:

   • Driver ID, for internal use.

   • Driver name, for display to users.

   • Driver software location. This might be its main class name. (You will, of course, have to figure out how to invoke this software.)

   • State: is it available (switched on)?

   • Version number.

   • Developed by, especially if by a third party.

   • Help page file name and location.

   Also consider what effect changing any of this information would have. If it could cause damage, think of ways to prevent it.

2. Switching from one driver to another For some types of driver, it is necessary to impose restrictions or to define guidelines for use. For example, you might be building a product that allows your customer to choose which encryption algorithm to use-but if letting them change their mind after going live is too hard, prevent them doing so.

3. Upgrading a driver See the inter-system interface requirement pattern in Chapter 5, because similar issues apply in both situations.

Considerations for Testing

Treat the testing of a driver the same as the testing of any other software. Much depends on the nature of the driver: testing the saving of data in a pluggable file format is a different matter from testing credit card payments.

If there are multiple drivers, test that the results obtained from each one is compatible with the others. For example, if all drivers are expected to deliver identical results, do they? This doesn't apply to all types of driver. For instance, drivers for saving data in different formats will be expected to produce difference results.

Test adding a new driver. Is it as easy as it should be? When testing the initial system, begin with at least one driver of each type missing and then watch closely as they are installed. Because an extendability requirement is basically a message to developers, talk to the developers about what they've done about it; ask them what they'd have to do to add a new driver.

Test different versions of the same driver. Test upgrading from one version of a driver to the next version. These kinds of tests might not be possible if only one version of each driver exists, which is often true for a new system. If not, quiz the development team about the provisions they have made for upgrading drivers.