Posted by s.crouch on 26 April 2012 - 9:00am

By Steve Crouch.

You're about to embark on the development of a new piece of software. Of course, there's a whole host of things you should do. But let's look at the flip side of the coin: what shouldn't you do?

1. Don't develop code that you can't maintain

It's all too easy to fall into bad habits, especially if you're up against a tight deadline. In the long run, good coding practices will save you a great deal of time and stress. It will also make growing the software a far more enjoyable process. After all, who likes fighting their way through an unclear spaghetti of code just to make a basic modification?

At the start of a project it's not always clear who else will become involved in developing the software. If other developers join your project, they will need to understand the code before they can develop it themselves. Good code can avoid a lot of problems (and embarassment when you show other developers!).

Writing readable, commented, easily understood and well-structured code doesn't take as much effort as you'd think, and it's even easier with the Institute's handy guide on developing maintainable software. You should also code defensibly - avoiding unnecessary and complex dependencies and deprecated interfaces - which is covered in our defending your code guide.

2. Don't make your software difficult to build and install

You've probably disregarded other people's software because it was too hard to build or install. The same rationale applies to your software: if people can't quickly get it to work, they'll not become users.

If you want your software to be usable by others, then the build and installation process should be simple, and possibly automated. The build and install processes follow a common sequence of instructions, and grouping these into a minimal set of scripts where possible will save would-be users a lot of time.

3. Don't keep the source code to yourself

You've started development, you've coded like crazy (but in a very sane and maintainable way) and have made great progress. At what point should you consider hosting your code somewhere other than your development machine? The best time is as soon as you start coding.

You don't want to lose your code. Your development machine could suffer a fault or, if it's a laptop, you could lose it or have it stolen. A code repository is a very good idea. If you don't mind others being able to access your code (or if you want them to), then GitHub or SourceForge are good choices. They're free to use and have a wealth of features. If you don't want to host your code publicly, then perhaps Assembla is for you. For more information, take a look at our top tips on migrating to an open-source repository.

If you start using a repository early you can take advantage of its more advanced functions, such as a full, code revision history, tagging for releases, and branching (if it becomes necessary). And most public solutions offer other handy community-oriented capabilities, such as issue trackers, release-file management, news, wikis, forums and mailing lists, as well as the ability to define access control for all these aspects including contributions to the code repository. The Institute has a guide to help you decide on the right repository for you.

4. Don't forget documentation

Yes, writing documentation can be boring, but it is the primary means of communicating to your users what the software is about and how to do stuff with it. Documentation doesn't have to be encyclopaedic... but it should definitely exist.

As the developer, it's all too easy to make assumptions about what is obvious, so adopt a green-user mindset towards documentation. The key is to define what is necessary, and build from there. A great place to start is a quickstart guide, which gives a basic overview of the software and instructions to install prerequisites, get it built, installed and working. If you've put effort into making the build and install processes easy or even automated, this should be really straightforward. Consider what more detailed documentation is required. Do you need additional documentation for developers, end-users and system administrators?

To avoid frustrating your users, the accuracy of your documentation is vital. Explain everything in a step-based manner, and don't be too expansive. There's no need to tell beginners about everything your software can do - that can be covered in a separate reference guide. As your software evolves, the documentation should evolve too. It requires maintenance just as software does!

5. Don't overlook testing

It seems obvious, but you need to make sure that your software works! An easy (and common!) trap is to release a new feature without properly testing it. It's not just that the new feature might not work, it's implementation might have broken an existing feature. Cue frustration in your users...

Instead of simply running a manual test for each new feature, why not put in a little extra effort and write a unit test for it? Once complete, you and your users will have an automated way of verifying that feature. Unit tests are also handy as a reference for developers on how to code against that capability. Unit tests also provide a framework against which other developers can test the new features they have developed.

You can go one step further and automate the running of unit tests. This creates a fail-fast environment for developers to test and verify their modifications, which will help improve the quality of code contributions. You could also run the automated tests on a nightly basis and publish the test results, or even performing a build, test and install when new code contributions are uploaded (known as continuous integration). There's more information in our guide on testing your software.

Avoid the pitfalls above and you'll have better software and happier users!