Best Practices - How KEP3 develop software

Version: 1.1

Release Date: Oct 29, 2002

Author:Johan Borg, KEP3

Introduction

This document will list numerous best practices that are applied to our projects. Not all fit fit to all different kinds of projects, but if they do, they help us deliver the correct software according to schedule, within budget and without forcing all involved to work 50% overtime. (Something which hardly produces any actual gain in productivity anyway.)

The practices are divided into "Must Do" for the crucial activities and "Optional" which may or may not be suitable depending on the project.

Worth noting is that we do not list fundamental practices here. Those are the obvious practices that really goes without saying, for example:

• Doing proper requirements analysis
• Creating an architecture
• Producing readable, high-quality code
• Quality Assurance

Instead we concentrate on particular aspects of the fundamental practices, like Quality Assurance: Inspections.

Must Do

Source Code Version Control

It does not matter whether one uses MS Source Safe or CVS. (CVS is free after all and it works fine.) What matters is that a package is used. Apart from relieveing everybody from the stress of figuring out what the other developers have been doing, source code control also works as a safe for the source code. There are still teams that loose source code thanks to crashed hard disks, stolen notebooks etc. Source Code Control helps by distributing all source code to all developers. It would be almost impossible to loose more than one developers work for one day.

Daily Build and Smoke Test

We want to completely build the software project and run it through a series of tests to verify the basic functionality. The build should work without any compiler errors or warnings and the test suite should not cause the program to go up in smoke. The significant advantages include:

• Minimizing integration risks
• Reduces risk of low quality
• Supports easier defect diagnosis (combined with Source Code Version Control)
• Supports progress monitoring

Bottom line is that this is a risk management practise.

One Step Builds

To be able to do daily build and smoke tests without slowing the development team down to a grind, it is of absolute importance to set up a build system that is literally as easy as pressing a button or issueing a single command. It is also of importance that the one step build does not just create an executable file, it should do everything from checking out the latest source code, compiling every line of code, create the executable, package it for installation and create the final media; CD-ROM layout, zip file, web site page for download, or whatever is appropriate.

The moment this process starts to include 20 steps of varying complexity, it is bound to introduce errors and it might cause a stop in daily build and smoke tests if the going gets tough.

Bug Tracking Database

None but the most trivial projects can survive without a bug tracking database. Even a single person working on a single project can not keep track of all bugs in the mind. It just doesn't work. A bug tracking database does not have to be complicated. Five items is all that is really needed:

• Steps to reproduce the bug
• Expected behaviour
• Actual (buggy) behaviour
• Assigned to
• Fixed or not?

Fixing bugs before developing new features

The longer one wait to fix a bug, the costlier (in time and money) it is to fix. Compare the extremes of the compiler finding a typo, and rejecting to compile, with finding a bug in a product that has already shipped. The other reason for fixing all bugs before implementing new features is that as long as there are unresolved bugs, the schedule for the project is plainly put unreliable. This is because it is very difficult to estimate the time needed to correct bugs. It is (comparably) rather easy to estimate how long it would take to implement a print preview, but how does one estimate a bug that causes the print preview to display garbage when, and only when, service pack 2 for Office is installed and the printer is a Samsung laser?

Using a Methodology

This is a fundamental practise but it is included here anyway. It is just not possible to create any software without following a basic methodology. Without going into detail (overview of methodologies), there is a single, crystal-clear, reason to use a methodology:

• A specific, well defined, problem may take anything from 1 hour to several weeks to solve, depending on where in the software development process it is done.

Something that might have been solved in an hour during the analysis phase, 5 hours during the detailed design, etc., might take two months to sort out after the product has shipped and it is finally discovered. I.e. one hour can be worth a lot more than one hour if used correctly. If one does not follow a methodology, there is no way of telling whether the hour spent is worth one, just half or maybe 200 hours.

Inspections

Inspections can be seen as a kind of formal technical reviews. They should be more formal than a peer review and the goal is to really have a constructive discussion on the merits of the reviewed material. To achieve this participants will be assigned clear roles as "author", "moderator" and "reviewers". Inspections can, and should, be applied early in the development cycle, working with requirements, architecture, design, code, etc.

Experience has shown that inspections can find 60 - 90% of the defects in a program, vastly superior to traditional testing or code walkthroughs. And since inspections can be used so early in the cycle, significant schedule savings can be achieved.

It might seem as rather formal and cumbersome method, but our experience, and industry research, shows that this is a safe way of ensuring that the one hour becomes worth more than one.

Top-10 Risks List

This list is a simple way to monitor a software project's risks. It should contain the most serious risks, current status, and most importantly the plan for addressing each risk. The list should be updated weekly.

The main benefit of the Top-10 (the number is of course not important) Risks List is that it enforces reviewing risks regularly and alerts to changes in importance.

Using the Best Tools money can buy

Considering the actual cost of developing software there exists no excuse for using less than optimal hardware or software tools:

• A standard PC is today so cheap that the cost equates to just a couple of hours of development time. Buy the fastest available.
• If doing GUI work, use two monitors. Cost is insignificant in comparison to the productivity increase.
• Harddisk space cost next to nothing. Don't spend time cleaning up, just add network storage.
• Buy good support tools. Anybody who has tried to do bitmaps or icons for GUI using MS Paint can testify that it just doesn't work.

What one should not do on the other hand is to:

• Use notebooks as development computers; it just doesn't work. If people need a computer at home (and they for some reason do not have one...), it is still cheaper to buy two stationary computers.
• Spend money on fancy office furniture and similar. There is not a single developer who'd rather have a nice antique (impractical) wooden desk over a plain but functional table of twice the size.
• Buy expensive, and more importantly complicated, software engineering tools (CASE tools) before the need is really established. It is very easy to be swayed by marketing speak about how their products will revolutionise your software development process. (Rational are very good at this.) Reality is not always that simple. Outgrow the easy tools first.

Use the Right Tools for the job

We strive to always pick the right tools for the job. We are not bound to any particular platform or software vendor. We also hold no aversion against any platform or programming language. We will look at each problem, determine what the real goals are (implementation speed, quality, portability, etc.) and from there make our recommendations.

Optional

Designing for Change

This item should perhaps for most projects be listed as a "Must Do", but there are projects where the requirements are well known and fixed, and for those projects designing for change does nothing but adding time and cost to the schedule.

On the other hand, for the other 99 or so procent of all software projects, change is the rule rather than the exception and it must be considered. Included in this broad concept is:

• Simplicity (simple things are just easier to change)
• Identification of areas likely to change such as:
  • File Formats
  • Inputs and outputs
  • Business rules
  • Sequencing
  • Data Structures
• Use of Information Hiding
• Development of a Change Plan
• Partitioning of the product
• Use of Object-Oriented Design (does not have to use OO Programming)

Unless explicitly declared, all projects should consider change and be prepared for it.

Change Board

A Change Board is an approach to control changes to a software product. It brings together representatives from for example developers, QA, marketing, end-users, etc. and gives them the final verdict on which changes should be incorporated in the product.

The change board is an excellent way of controlling feature (scope) creep, raises the visibility of the proposed changes and achieves consensus among all involved parties.

Reuse

Contrary to common belief Reuse is not a silver bullet that immediately and automatically produces a huge increase in productivity. At best it can, but at worst it might lead to a lot of wasted effort (because the modules selected for reuse are not selected carefully). It is important to distinguish between the different sorts of reuse possible:

• Planned Reuse
  • Long term strategy. A culture must be grown. Works best on the fundamentals of the business that are not likely to change too much over time.
• Opportunistic Reuse
  • A short-term practise of using code from existing programs in new programs. Easy to overestimate the savings; requirements, design, testing, documentation, etc., still has to be performed.
• Reuse of third-party components
  • More often perhaps labelled as "Buy-or-Build" but the basic issues are the same as for opportunistic reuse. Again savings might be overestimated. It might even be that the component solves 90% of the functionality, but not more, and a custom solution has to be developed anyway.

Reuse is a powerful technique that can reap huge benefits under the right circumstances, but it has to be applied with judgement. It must always be remembered that making a component reusable multiplies the implementation time by a factor of three (on average)!

User-Interface Prototyping

In projects where the user interface is central to the acceptance of the project as a whole it is worthwhile to tackle this head on, as early as possible, with prototypes. (Basic risk management.)

The prototyping can be done in the target language, a specific prototyping language or even on paper. The purpose is to agree upon the requirements for the application as early as possible. With GUI work in general there is a huge discrepancy between users perception of the program and that of the developers. For the users the GUI typically represents a major part of the application. It is what is visible after all. For the developers the GUI is usually a very small part of the application. This discrepancy must be taken into account to ensure that expectations are not set too high after a GUI prototype.

Second important consideration for user-interface prototyping is whether it should be Evolutionary Prototyping or Throwaway Prototyping. This has to be decided beforehand.

Refactoring

Refactoring is the principle of improving existing code without changing the functionality in any way. This is a very powerful technique that vastly improves the quality and maintainability of code. As a basis we use Martin Fowler's excellent book Refactoring.

Refactoring might from the outset seem like a method of spending effort without getting anything in return; since the functionality should not change. But what one does get is a much higher quality of the code since the refactored code is is in general simpler. This of course also improves the maintainability.

Worth noting is that refactoring is not for all projects. Short lifespan projects that are not intended to survive for long does of course not benefit. And if, after all, the project gets a second life, it is more than possible to start the "Version 2.0" development with refactoring of the old.

Acknowledgements

The original ideas for many of these practices come from well regarded people within the industry like Steve McConnell or Martin Fowler. While many more practices can be found published by these and other authors, we have limited our list to the ones that we find truly useful in almost any situation.