Software Structure Defined

Non-functional requirements such as software extensibility can be very difficult to document as we likely do not know all of the future features or growth we can anticipate for the product as it matures.  Poorly managed, the code may descend into what is sometimes referred to as spaghetti code.  Instead of the document focusing solely upon the features, we can put some requirements for the structure in place before the coding even begins.  A way to do this is through the use of a software design description document.  This document may be especially important the first time working with the vendor or if there are some questions about the maturity level of the software department.  It may not be necessary to create a software design description document for every project.  An organization of a sufficient maturity level may not require such an artifact.  We can glean some understanding of an organization’s capability through reviews of the work processes and activities that are performed during the product development life cycle.

Software Design Description, Requirements, and Structure

The software design description defines the attributes of the software that go beyond the functional and performance expectation.  In this document, the expected structure of the software, software modules, specific interfaces, and data are described.  Defining the structure is important because poor software structure can make the future growth of the product resemble either a well thought out nice addition to our home or some glommed on a disparate piece of work with the associated quality issues.

For example, design entity or specific modules are called out in the software design description standard described in IEEE Standard 1016-1998.  This section of the document places specific expectations upon those creating the software when it comes to software modules.  As the WBS is for projects, the design entity is for software creation.  Specifically, the design entity breaks down the software systematically, identifying the software modules that will be required for the code that will achieve the objective of the product. 

Defined Structure Articulates Expectations

We receive two benefits from this activity. The fist is we will have a better chance of building a well-structured code. If we are the customer and understand what well-structured code is, we articulate our expectation to the supplier in a way that will enable them to meet our expectation.  If we do not have the expertise, we can review this document to learn and question the approach even before we start coding, for example via a review of the document, giving us the chance to identify potential failures in the software structure from the start.  The second benefit comes when we consider extensibility of the software.  We create clean boundary conditions where updating the software at some future date will only require modification or rebuilding few modules instead of creating and weaving in additions around some randomly developed structure.

In addition to identifying the unique software modules, we describe specific attributes of those modules. These specific attributes provide a point at which we can verify the module has been built to expectations.  These are tangible statements that can objectively be tested and certainly be audited or reviewed.

I encourage all who develop software to check out the IEEE Standard 1016-1998.