Avoid Side-Effects

A side-effect of a procedure is something the procedure does that is not its main purpose and that is visible (or whose results are perceivable) from outside the procedure. Side-effects are the sources of many subtle errors in software, that is, the ones that are the most latent and the ones that are most difficult to discover once their symptoms manifest themselves.


Reference:
Ledgard, H., Programming Proverbs, Rochelle Park, NJ: Hayden Book Company, 1975.

Keep the Requirements Specification Readable

A requirements specification must be read and understood by a wide range of individuals and organizations: users, customers, marketing personnel, requirements writers, designers, testers, managers, and others. The document must be written in a manner that enables all these people to fully appreciate the system needed and being built so that there are no surprises.

Creation of multiple requirements specifications (each for a subset of the stakeholders) works only if you can guarantee consistency across the versions. A more effective method is to maintain the natural language (Augment, Never Replace, Natural Language) while incorporating multiple views of a more formal nature (Use Multiple Views of Requirements and Reduce Ambiguity in Requirements).

I want to stress the importance of keeping requirements specifications consistent. Many teams find it helpful to use a wiki, such as Confluence, to keep an easy to read and unified version of the requirements specification while using a ticket system, such as JIRA, to document the stories and technical tasks. If these two systems are not kept consistent then the project becomes much more difficult and understanding is lost.


Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, Englewood Cliffs, 1993.

Identify Subsets

When writing a requirements specification it is important to clearly identify the minimal subset of requirements that might be useful. This is also known as identifying the minimum viable product. Now, extend that minimum viable product concept across the timeframe from when development starts and the completion of the product. Identify the minimal increments that might make the minimal subset more and more useful. Such identification provides software designers with insight into optimal software design. It will enable designers to:

1. More easily embed just one function per component.
2. Select architectures that are more contractible and extendable.
3. Understand how to reduce functionality in the case of a schedule or budget crunch.

A very effective technique of recording subsets is to rank the order of a products features by value. Compliment that ranking by grouping features into minimum viable products over the schedule of the product. Take your software requirements specification (SRS) and include columns in the margin beside each requirement. Each column corresponds to a different version of your product. These versions can represent multiple flavors of a product, each tailored to a different customer or situation, or they can represent increasing levels of enhancement through time. In either case, place an "X" in the appropriate columns to indicate which versions will have which features.

Reference:
Parnas, D., "Designing Software for Ease of Extension and Contraction," IEEE Transactions on Software Engineering, March 1979.

Don't Ignore Technology

Software engineering technology is evolving rapidly. You cannot afford to sit around without keeping abreast of new developments. Software engineering appears to grow by waves. Each wave brings with it a large collection of fads and buzzwords. Although each wave appears to last just five to seven years, the wave does not simply disappear. Instead each subsequent wave stands upon the best features of all previous waves. (Hopefully "best" means "most effective," but unfortunately it often means "most popular.")

I know of two ways to keep abreast of the technology: reading the right magazines (and books - if very recently published) and talking to the right people. IEEE Software and Communications of the ACM magazines are a good place to learn about what's likely to be useful in the zero-to-five-year timeframe. To learn from talking to people, you must meet the right people. Although talking to folks in your own organization is necessary, it isn't sufficient. Try attending one or two key conferences per year. The presentations are probably not as important as the conversations you have in the hallways.


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Different Languages For Different Phases

"The industry's eternal thirst for simple solutions to complex problems (Every Complex Problem Has a Solution) drives many to declare that the best software development method would use the same notations for software representation throughout the entire development life cycle. Since this is not the case in any other engineering discipline, why should it be in software engineering?"

"Notations provide us with models that can be manipulated in our minds. The more notations and the richer and more diverse the representations used, the better we can visualize the product under construction."

For requirements engineering, select a set of optimal techniques and languages:

• Use the Right Techniques
• Use Multiple Views of Requirements

For design, select a set of optimal techniques and languages:

• Evaluate Alternatives
• Design Is Multidimensional

For coding, select an optimal language:

• Use Appropriate Languages
• Programming Language Is Not an Excuse

"Transitions between phases are difficult. Using the same language doesn't help. On the other hand, if a language is optimal for certain aspects of two phases, by all means use it."


Reference:
Matsubara, T., "Bringing up Software Designers," American Programmer, July-August 1990.

Build Software So That It Needs a Short Users' Manual

One way to measure the quality of a software system is to look at the size of its users' manual. The shorter the manual, the better the software. The use of well-designed software should be mostly self-evident. Unfortunately, too many software designers fashion themselves as experts in human interface design as well. The voluminous manuals that result are sufficient evidence that most interface designers are not as great as they proclaim.

Use standard interfaces. Use industry experts to design self-evident icons, commands, protocols, and user scenarios. And remember: Just because software developers "like" an interface, it doesn't mean that your customers will have any idea of how to use it. Many software developers like interfaces with built-in short-cuts. Usually, customers want simple, clean, clear interfaces - they don't want to learn tricks to enable short-cuts.


Reference:
Hoare, C.A.R., "Programming: Sorcery or Science?", IEEE Software, April 1984.

Build Flexibility Into Software

A software component exhibits flexibility if it can be easily modified to perform its function (or a similar function) in a different situation. Flexible software components are more difficult to design than less flexible components. However, such components are more run-time efficient than general components and are more easily reused than less flexible components in diverse applications.

Pair Programming

I'm a big fan of pair programming. I have used it many times and almost everytime the result was better code that was developed faster. Pair programming is like having continuous code review.

Sadly, there is a lot of controversy with this particular agile/XP practice. Seeing two valuable resources sitting down at one computer makes most managers nervous. They think their team's productivity has just been halved. The worst thing about this mentality is that it makes it clear that the manager thinks programming is just typing.

Mere typing, programming is not. A good idea or a bug caught early on in the process can save a team a lot of work and rework later. By pairing you share valuable knowledge and practices throughout the team, catching more bugs early, and increasing code quality.