The Code Whisperer

I was in London all day yesterday and today has been spent trying to get a software release together and an odd error in Installshield is preventing this.

My usual buffer of postings has been exhausted, so today I’m going to post links to some other blog entries.

If, like me, you don’t like fingerprints over your screen, you will agree with Jeff Attword in his post on the subject. A bit extreme, but I know where he is coming from! www.codinghorror.com/blog/archives/001115.html

The second is from Steve McConnell. He’s carried out a survey on the classic mistakes presented in his Rapid Development book, which are the basis of the current series on this blog. The survey can be seen here: Classic Mistake Survey

Steve has also updated the Classic Mistakes list recently and we will cover this once we’re past the first 36. The 7 new mistakes are list on this post: Classic Mistakes Updated

A few years ago, and much to my wife’s horror, I took a book called The E-Myth Revisited by Michael E. Gerber with me as holiday reading. In this book E stands for Entrepreneur rather than Electronic, and through examples it demonstrates the value in having business processes documented. The idea is that as the fledgling company grows, you can employ staff who are smart and can get things done, point them at the procedures manual and they should be able to get on with the job with a minimum of time consuming supervision, something the growing business doesn’t have a lot of. This frees the business owner from doing jobs in the business he or she shouldn’t be doing and lets them get on with working on the business. Part of the reason that some of the fast food franchises are just about identical the world over is because each franchisee has an operation manual explaining exactly how to run the business. It is one of the best business books I’ve read.

Unwittingly I’ve been producing procedure manuals in various forms for years. When I was rallying we had a ring binder with laminated instruction sheets for various jobs on the car. If we needed to swap parts or make adjustments during service time we had detailed instructions on how to do it, so that the work was completed in the shortest possible time.

A Paul Gorman seminar I went to in 2006 had a guest speaker from a company that hired broadcast quality video camera equipment from their office in London to world locations. Kits were tailored to the needs of the individual hire and sometimes, generally due pressure of time, essential bits of the kit were left out. Fed up with checking each kit personally, the managing director instigated complete documentation of the company’s processes and added checks at various stages of despatch to at least reduce the number of mistakes being made. Once this had been completed ownership of the process documentation passed to the individuals involved in that part of the company. If they could improve the process they did, and documented it. The quality perceived by their customers soared - the equipment was identical, simply the correct equipment was being delivered. The company ran smoothly and when a kit sent out failed, a task normally handled by the managing director who was away, the staff member simply located the process documentation, followed it and the crisis was over by the time the managing director appeared in the office.

I highly recommend reading Michael Gerber’s book, even for large companies. It was a real eye-opener for me and now we document every process Operations Support does. Our documentation is simple and effective, a well indexed word processing document with plenty of screen shots and photographs.

If you decide to create a procedures manual, I have a few pointers:

• The aim of documenting the procedure is so that pretty much anyone could pick up the document and complete the process, so write accordingly. Consider a glossary if jargon or abbreviations are commonplace
• If possible have someone who isn’t familiar with the process try out the documentation - you’ll soon find out if there are any bits that need further explanation
• As in out video camera example above, the point of the documentation is that it’s followed. There really is not point having it if it’s not used on a day-to-day basis. Consider having check lists to help verify that the process has been carried out
• Make sure the procedures are available to all the staff members that need them. Obviously you need to be careful with some areas of the company, for example accounts. Print copies of the procedures and keep them up to date, so that you are not reliant on the computer being available. Laminating is a good idea if there is a chance that the sheets could get mucky, as I did with the rally car book
• Involve your development team in the documenting process. Make sure they understand they are part of the process and they have a say in it. All you are doing is making it easier to get things done, there’s no performance measurement involved

I really hope this is a topic you can ignore, but I’m going to cover it anyway.

In the late 1990’s I was involved in a major project for a prestigious motor manufacturer. Having very good cashflow they weren’t adverse to spending a bit of money, so I was horrified when I found out that the source control server, with 6 months worth of design and development work on it, firstly wasn’t being backed up and secondly wasn’t in the server room but in the development team’s office situated under an air conditioning pipe that had developed a leak.

Let’s have a look at some data loss scenarios and how they could be recovered from, assuming the appropriate backup policy was in place:

Developer checks in the wrong code
Roll back to the previous version in the source control system. No loss of work.

Developer loses or corrupts checked out code
Revert to the previous night’s backup, loses up to one day of work.

Developer machine corrupt
Re-image the developer machine, get the latest source from the source control and restore the previous night’s backup, loses up to one day of work.

Source control server corrupt
Restore the source control from last night’s or later backup. Checked in code since backup may reside on developer’s machines. Worst case scenario is that each developer loses one day of work each, although this is highly unlikely.

Office destroyed
Build new source control server and restore the source control content from the last off site backup. Build new developer’s machines using image of developer’s machine held off site. Get latest source control on to developer’s machines. The amount of work each developer loses depends on how often backups are sent off site, but this could be as little as one day.

This last scenario is drastic but does happen. To be honest if the office has been destroyed there will be other factors to consider, but with the right backup strategy and a trip to the computer retailer you could be up and running really quickly.

With backing up across the Internet now available and very cheap, it’s possible to build a backup strategy that offers maximum protection with the minimum of fuss. Backups are only important to people when things go wrong, so generating them must be as effortless as possible.

Here is our backup strategy:

• Source control exists on a server in our office. Code is checked in as soon as possible provided it compiles
• The source control repository are backed up across the Internet to Data Deposit Box. The Data Deposit Box software runs on the server and detects changes to the repository, extracts, compresses and encrypts them, then securely transfers them to their secure data centre where they are stored in encrypted form
• Source code changes not checked in are backed up at the end of the day to a file server in our office. The developer’s machine has backup software that backs the files across the network and then shuts the machine down. This backup also includes Outlook PST files
• Other files such as documents and images are held on network file servers never on individual workstations. Documents and selected other files are backed up to the Data Deposit Box servers using the same technique as for the source code repository
• A disk image of a developers machine has been taken and is kept on a file server
• Copies of virtual machines are kept on the file server and backed up from developers machines weekly
• File servers are backed up completely to external hard drives, which are stored off site
• USB memory sticks are used to hold backups of this blog, software and licence information for developers products and the latest release code for our products. These are backed up to a files server and tend to go everywhere with me
• Software installation CDs are kept in a fire safe in the office

I believe this is a pretty comprehensive backup strategy and with the use of Internet backup I’m confident that we could be up and running in a different office in a matter of hours if total disaster did strike.

I’ve seen this so many times. A design or requirements document is produced for a system and shown to a number of people. And one person doesn’t like it, so they shout loud and long. Often this someone in a senior position and who won’t use the software in any case.

The most damaging case I’ve experienced was in a meeting with a photocopier manufacturer, who wanted to expand their system to handle rental of fax machines and had employed the consultancy I worked for to carry out a feasibility study. Early on in the meeting one of the participants suddenly blurted out “we can’t do this, it’s against the business model” and went into a five minute rant and stormed out. Being slightly worried about the political implications of this event I asked what position the they held in the organisation. It turned out to be the secretary to the sales director and not someone who could determine the future direction of the company.

My point is quite straightforward. When evaluating feedback look at every comment and, initially, ignore the source so that the outwardly passionate comments don’t swap comments made by others, who may be just as passionate, but not so vocal. In the cold light of day you would value the comment of someone that uses the software every day if it conflicts with comments from someone that is a casual user, but pays your wages. In practise this is hard to do, but there is something you can do to make a decision based on quantifiable data: usability studies. A mixed group of users, different systems, a video camera and with websites a product like crazyegg will provide additional analysis. A usability study takes some setting up, for a start there needs to be two user interfaces to test, but it’s better to make a decision now that creates a superior user interface that people will use than have to either have a product that people don’t like (and will be reluctant to use) or have to release a revised UI in a short space of time.

Software Development Metrics

In an earlier post we looked at measuring software development and finished by listing metrics suggested by Steve McConnell in Code Complete. Here’s the list again.

• Lines of code
• Work hours spent
• Number of times routine changed
• Cost
• Defect location
• Defect severity
• Defect originator
• Number of lines affected by a defect
• Time to correct a defect
• Number of attempts to fix a defect
• New defects resulting from corrected code

Here’s a few examples on how the metrics can be used, assuming that defects are spotted in system testing by the test team and not part of development:

Number of defects / number lines of code (often multiplied by 1,000)
Indication on the quality of the code released to system test. The defect could be due to the interpritation of the requirements or interpritation of the technical design, but this metric can be used to judge the effect of implementing code reviews or a change to the technical design layout or content.

Number of time routine changed
High value may indicate insufficient or changed functional requirements, poor quality technical design or coding. Again this metric can be used to judge the effect of implementing code reviews or a change to the technical design layout or content.

Number of attempts to fix a defect and Time to correct a defect
A high value may indicate insufficient information on the defect, creating of new bugs when fixing (unless this is being recorded in New defects resulting from corrected code) or could simply be a hard defect to correct. These metrics can help measure the impact of changing the information provided by the test team on each defect, although to have a balanced view it’s necessary to know how much more time is spent by the test team in adding the additional information.

Defect location
This is identifying the location in the code of the defect and can be at a high or low level as you want to record, possibly identifying a poor technical specification or interpretation or a complex part of the application.

Defect originator
The important factor with this metric is not to start a witch-hunt for the developer, but determine why if they are producing a high number of defects. It could be they are working on a more complex part of the system, or they require additional training. The good thing is having used the metric to determine the problem, the metric can be used to see if the situation responds to the changes you make.

Be careful comparing metrics across two different projects. There is a golden rule - no metric or combination of metrics can compare projects of different complexity, without clarification. Whilst defects per thousand lines of code could be used to compare two projects, it takes no account of the complexity of either project, hence the need for clarification. Metrics such as lines of code and work hours spent should never be used to compare projects with the slightest difference.