Title: Professionalism in programming Part 3

Software needs documentation. Just how much documentation is a moot point. The user of a Windows office suite certainly thinks there should be more than the supplier does. As software producers by not writing documentation, we forego the chance to shout RTFM to the thick users who ask banal questions about our product. I don't think that anyone will argue with the usefulness (or necessity) of this sort of documentation.

But just as the final software product needs documentation, so do the intermediate steps in the process. This is the sort of documentation that the user will (usually) never see. These are the definitions of how the program will be designed and built. These are the software specifications.

Writing and working to specifications is a big part of Doing Things Properly. In this article we're going to investigate what sorts of specification we need, what should be in them, and why reality differs so greatly from the ideal.

Specifications are system and process documentation. There are many different types of specification that are related to the software construction process. Their scope ranges from the conception of the project to the final deliverable. They include specifications detailing exactly what the user requires (or exactly what they are going to get, if the two differ - they usually do), specifications detailing the architecture of the software solution, the interface a particular module of code has to conform to, of the design decisions relating to a particular piece of code, and more.

Specifications are formal documents that are visible to all relevant parties.

So what do specifications give us that means that we need to write them? Hopefully this is obvious, but that does not mean it is not worth cataloguing.

Specifications are a form of inter- and intra-team communication. We said in the last column that projects really do die of a lack of communication. Therefore we should use specifications as a communications medium as much as we can - but only where appropriate. Projects can just as easily die because too much time is spent writing documents, and not enough time is spent actually delivering product.

Specifications are often the intermediate 'gates' of a software development process. They form a kind of contract between two stages of the process. For example, a specification for the interface of a particular software component is written by the group of people who are scoping the functionality and environment the component should exist in - this is the analysis/design phase. In the implementation phrase the implementor of the component need only see this specification; it should be complete enough for them to write the component. In this sense the specification is a contract detailing what the systems integrator expects from the component and what the implementor needs to create. If either party deviates from the specification then they are in error.

Since errors such as these are measurable against the specification, it makes the software development process less hard, safer, accessible, and more repeatable.

I would (perhaps contentiously) argue that specifications become increasingly important as the size of a project increases. This is not because specifications are not important in smaller projects, but because in the larger projects there is more to loose - there is a greater number of people whose lack of co-ordination will have a greater impact of the outcome of the software development process.

As a student I remember being annoyed at being set an exercise which was practically impossible because the question was vague and could be interpreted in one of two ways, The specification for the piece of work I was set was not suitable. Very recently (as a professional) I've been annoyed because the specification of part of an embedded operating system[Bradner] was too vague, and I was not sure how to use it.

Good specifications and documentation are generally taken for granted, whereas poor specifications and documentation rapidly become loathed.

But is a poor spec better than no spec? If it's factually incorrect it definitely is not. If it's ambiguous then it's a borderline case, depending on whether the engineers are experienced enough recognise so. But a specification should really stand on its own and not be defined by its readership. If its too verbose and hides information then it may be better (in the long run) to rewrite.

There are in reality many different types of specifications. Below I list the most common ones. Naturally since we live in the real world, no one calls them by the same name. For example, a 'requirements specification' is variously called 'user requirements specification' and 'functional constraints specification' by different companies.

Obviously each of these different types of specification contain different material. However, there are characteristics applicable to all types of specification.

A specification should contain at least: an introduction, a scope and purpose section, any relevant definitions and a set of references. This ensures that the document is self describing and that a reader will be able to access the information contained within easily (e.g. they will know what knowledge is prerequisite to reading).

Where appropriate a specification includes any constraints, assumptions and dependencies that are relevant to ensure that there is no ambiguity.

When writing a specification the use of language should be carefully made. Specifications are formal documents, and so must not be chatty or verbose (this tends to hide the important facts behind a wall of words). Formal documents are written in the third person, in present tense (i.e. you write must/should not will) [Bradner].

Ultimately, the specification should follow the document standards/conventions of the company. If the company does not have a standard (or some form of skeleton document) then you should worry!

Technical writing skills do not always come for free with an engineer. Some engineers are better at it than others. However, if a software engineer is not capable of documenting work that they have produced then they are a liability. Practice (followed by review) makes perfect.

The best specifications are written from the perspective of the reader, not the writer. The information is organised in such a way as to make it more comprehensible to someone new to the item, rather than in a convenient form for the writer. Writing specifications in this manner does require more work and take more time, but it's worth it if the result is simpler to understand. Blaise Pascal once wrote "I have made this letter a rather long one, only because I didn't have the leisure to make it shorter."

In the real world, decent specifications often get overlooked. Why is this?

Engineers do not write specifications for two reasons:

If an engineer forgets to write a specification or does not know that they should be writing one then they are quite likely inexperienced. They need to be told to do so by their manager.

Programmers like to program, not write. Many programmers do not have good writing skills. Kent Beck will argue that it is not their job and the documentation is in the code and its set of tests [Beck]. Many programmers try to avoid writing specs since their technical writing skills are not that good, or they just do not like doing it.

The main reason an engineer chooses not to write a specification, though, is that they do not appreciate the value of the specification. Too often it's seen as a time wasting activity that is really not necessary. Or they think 'I'll code first, then come back to the documentation later'. Bitter experience has told us time and time again that this does not happen.

Experience has also told us that code written without any forethought (the kind of forethought writing a specification makes you perform) is worse code. It is code that is badly designed. It is code that is hard to understand. It is code that doesn't fit into the overall system properly. It is code that is hard to maintain. It is code that costs more to create and maintain than if it had been properly specified in the first place.

Having said that I can cite a recent occasion that I did not start by writing a specification for a particularly important piece of code, an interrupt service routine. I started to write the routine on Monday, the code was due to ship on Thursday. You would like to think that this kind of thing does not happen in the real world but it does. Why did this situation occur in the first place? An inadequate specification elsewhere!^[2]

We have seen what specifications are, some of the different sorts of specifications that exist in the programming world, why we write them, why we do not write them, and why our wrist should be slapped because of this.

If any readers would like to describe why projects they have been on have got stuck for lack of decent specification work then it would be a valuable cautionary tale to the rest of the C Vu readership.