Move beyond mere source control to the problems source control doesn't solve

by Robert L. Bogue | May 15, 2006 8:07:00 PM

Tags: Databases, Development tools, Robert L. Bogue, source control system

Takeaway: In this document, we explore the common problems that a source control system won't solve and talk about what you can do to make progress on these items so that your overall coordination of the project team will be easier and more productive.

If you've ever working on a multi-person development project that didn't use some sort of source control system, you're probably painfully aware of what it feels like to loose some of your hard earned work. Sure you may be able to reproduce the work but the feeling that you've already made the investment to create it once is very nagging.

Even if you've used source control systems you may have noticed that there are certain problems that a source control system doesn't solve. Managing configuration files, consistency of file locations, standard coding practices, a check-in schedule, and a build process are all examples of application development problems that having a source control system with check-in and check-out won't solve.

In this document, we'll explore the common problems that a source control system won't solve and talk about what you can do to make progress on these items so that your overall coordination of the project team will be easier and more productive.

Configuration file management

Configuration files are problem files in source control systems. The file that causes the most problems with Web projects is the web.config file. Every developer needs to edit it to put their miscellaneous bits of configuration information in, but in most cases the configuration information in the web.config file is very specific to a developer's local working copy, the development environment, and the other environments that the system must work in.

It is because the file has so many developers working on it and because it ultimately stores configuration information for different machines that it's a difficult file to manage with or without a source control system. However, it isn't unmanageable; it's just difficult. Configuration files require special care even with a source control system. Here are some of actions you should consider when developing a strategy for dealing with configuration management issues in source control:

• Reduce -- Minimize the number of entries that contain machine specific information. This may mean standardizing on names and entering those names in a hosts file on the machine so that the settings themselves don't change from one environment to another. For instance, rather than referring to your database server as devdbsvr01, you can create a host entry myAppDBServer pointing to the same address as devdbsvr01. You refer to MyAppDBserver in your configuration file, and create hosts entries on each machine you install the application on. Those host entries point to different database servers for different environments.
• Separate -- Some of the information that ends up in configuration files are the values necessary for business processes -- settings that will remain the same no matter what environment the system is used in. Other settings are very specific to the machine or environment that is running. Separate these types of information. Perhaps force all machine specific information into a separate file that is managed separately from the business configuration. This will reduce the size of the information which must be maintained for each machine or environment.
• Consolidate -- In a multi-developer environment it's easy to get two or more configuration values that really mean the same thing, just to two different parts of the application. Be on the lookout for opportunities to consolidate configuration entries into fewer entries.

Bad code

Another problem a source control system won't solve for you is preventing developers from writing bad code. Every developer, me included, has written bad code. The code seems to work on the surface but there are lurking problems. Code reviews are designed to catch this thing but how do you do a code review on code that a developer changed even though it wasn't assigned to them? Certainly this isn't a source control problem; however, you can use the source control system to help you out.

You can use the source control system to create a check-in and differences report each day as you come in. You can review all of the check-ins from the previous day and for code which was revised. You can even see what lines were changed. This has the net effect of allowing you to know what code changed and who changed it. From there you can schedule some time with the developer, setup code reviews, or take whatever actions are necessary to create the quality code that you want.

File locations

One interesting thing that happens is the subtle changes that occur when a developer checks out files, particularly project and solution files, which can cause subtle problems for other developers. If a directory tree that doesn't match the source control system isn't used it will be difficult for others to compile projects because even relative paths to inter-project dependencies won't be right.

Insist that all developers us a specific drive and directory for all of their development (whether they like it or not!) Keeping a consistent build directory will reduce the number of build problems by developers, and make it easier to troubleshoot those build problems that do crop up.

Coding standards

No source control system implies standards; it is simply a repository that keeps multiple versions of files and returns them on command. So a file with the correct name will be accepted into a project even if the information in the file itself is complete gibberish.

A comprehensive, agreed upon set of coding standards aren't required or encouraged by a source control system, but they are essential to the long term maintainability of the solutions you're building.

Check-in schedule

Having a source control system won't help developers understand when they should check things into the build. There are at least two schools of thought on this. One school of thought is that every developer should check in their work daily. In this model developers are required to check in code at the end of each day. The other approach is that developers are required to check in code when it's ready for demo, initial testing, or some other milestone, arbitrary or not.

In the daily check-in process you must cope with a frequently broken build as non-functional code is added before it is ready. Because it's a checkpoint for developers before they leave, it often gets done in a hurry and without a reasonable amount of testing. On the other hand it definitely forces continuous integration which can identify gaps or problems quickly.

The process of checking in code when it's ready doesn't force the kind of daily integration that some organizations desire. However, it does mean fewer broken builds and less time tracking down build issues. On the integration side, you'll have to decide a reasonable timeframe to allow a set of code to be checked out without being checked in; the longer the interval the greater the risk of integration issues.

No source control system is going to insist on one approach or another, however, settling on a process for a check-in schedule is essential for getting the most out of the system.

Source control organization

Organization seems to be a struggle for everyone. Organizing solutions together and the projects within them can be a real challenge to get right. This is another place where source control systems will be silent. However, with many developers each checking in code for their own part of the system it's important that everyone have a clear understanding of where everything goes.

Develop guidelines for what the project hierarchy within the source control system should be. Make sure that all of the developers understand the organization and the fundamental reasons behind its design.

Build process

There are automated build tools and continuous integration tools which are designed to make the process of building the software completely automatic. While it is a worthy goal to try to implement these tools, in many cases, organizations have build processes which are poorly defined and the processes are rarely moved from one project to the next to capture best practices.

You don't have to have CruiseControl, NAnt, or even MSBuild in your toolbox for managing your build process; however, you should have a simple, repeatable process which anyone, including the administrative assistant for the team, can run. The build process should be documented and without ambiguity both to improve operations but also to address the potential need to move to production servers where developers aren't allowed to go.

More than control

Source control solutions don't solve every problem. They still leave you with unanswered questions. However, they are a great first step towards improving your software quality and protecting your aspects. Just don't forget to make some important decisions and create some guidelines.

Print/View all Posts Comments on this article

What is in your control? Mark W. Kaelin | 05/15/06

So, what do we do about these issues........ mherzog@... | 05/18/06

What level of detail? rob.bogue@... | 05/18/06

I'd just like to learn more mherzog@... | 05/19/06

re: Config Files Rod Wittmier | 05/19/06

Ant Configuration files and Build process CarlosAQ | 05/26/06