Email	Print Reprint
	add to:
	Del.icio.us Digg Google Furl	Slashdot Y! MyWeb Blink

Software Development

April 2006

If you are the development team, you've probably found that many software methodologies don't apply. We had a very small support department, and only survived on the strength of our documentation. Detailed records of what happened were life-savers when a similar problem cropped up a year later. Here are some sure-fire tips for increasing productivity when developing software on your own.

One lesson that I drummed into successive operators was that searchable content is more important than formatting. I banned the use of the word processor and we used simple text files on the VAX. Later, we graduated to the online help system because it was still easily searchable, but added some structure. Plus, You can't afford to rely on your memory if you can't guarantee how long you'll be working on the same task. The smaller the team, the more likely that your current task will be interrupted for a significant break.

Diary-Based Software Engineering

The essence of this approach is a series of diaries. The various diaries have overlapping information but distinctly different purposes. This is like documenting a design with overlapping scenarios and techniques—the redundancy helps you avoid missing any important points and all it takes is a text editor and optionally, a second computer to avoid flipping your current work out of view while you record it. Giraffe-necked UNIX programmers with 21-inch monitors are excused.

The Site or Project Diary summarizes external factors that may affect the project and to track interaction with the client such as changes in the environment, including hardware and incidental software such as the operating systems or anything that can affect your project, a log of installations and a log of user bugs.

The Random Thought Diary tracks ideas without in-depth analysis to quickly capture ideas before they fade, such as new features, problems you may encounter and need to research, and alternative implementations.

The Design Decisions Diary captures the basis for a design decision, the supporting arguments and rejections that prevents you from wasting time reinventing "brilliant" ideas six months later.

The Code Change Diary tracks code changes in enough detail to let you recreate or undo them.

The techniques I've discussed could easily be combined into a software product. A cross-reference database would be nice, as would reminders linked to the Thoughts diary. However, this simple text-based approach is small enough to be used and powerful enough to be useful.

Today, Diaries Revisited Ten years of thinking out loud Whilst a lot has changed in ten years, developers still need help to focus thinking. Feedback generally applauds it as a process small enough to be followed and still effective. Agile Development fits the diary-driven process nicely. Agile stories are natural topic headers for both diaries, providing briefing notes to get pairs up to speed An ever-growing document seems a natural for version control but can be a distinct pain. A single document is a choke-point for locking VCS like SourceSafe. CVS-style merges report conflicts if changes only ever append content. Individual diary files avoid VCS clashes and provide a coherent history, without distraction from flicking between writing styles. A single directory of multiple design diaries is not much harder to search than a single text file. A major benefit of individual code-change diaries is providing a place to compose check-in comments whilst the work is done. A typical terse couple of lines composed at commit time is instead a paste of what has actually been changed, saving the casual browser from having to diff each source file and making commit notification emails more informative. Code-change diaries with every change noted (horrors!) have been a harder sell in a team than the design diary. In four varied teams, I've found it best to lead by example. Even with management agreement and authority to dictate their use, a few months of seeing diaries accumulate in the project is more convincing, as individuals take their un-pressured time to adopt the practice. For distributed teams, particularly open-source groups, IRC or mailing list debates summarize nicely to design diary lists of alternatives and the every-important why. —Andy Dent

RELATED ARTICLES No Related Articles		TOP 5 ARTICLES No Top Articles.