Applying these seven simple source control tips will save your Eclipse-based project team hours of debugging and improve your code quality.
In only two seconds, just one developer with poor source control habits can cost the entire team hours of debugging. Fostering these seven simple steps for yourself and your project teams will save time and frustration while improving quality.
Tip 1: Use a Plugin
When I first started using Eclipse the company source control system was Microsoft Visual Source Safe (VSS). The VSS fat Windows client at the time was very easy to use, but it was very tedious to go back and forth between Eclipse and VSS, then navigate the source tree (again, having already done it in Eclipse) to find the file and check it out. I was already in the process of building out an Eclipse toolkit for myself, and decided early on that a VSS plugin was a must-have. The plugin allowed me to check files in and out without having to leave my development environment, and I could even configure it to remind me to enter check-in comments every time.
The Eclipse source control plugins have evolved to the point where you may never need to install anything else on your machine to use all the features of your source control application of choice (or your company's choice). In fact, many of the source and version control vendors' fat clients are Eclipse based (though the plugin is usually much less resource intense).
Below are links to the plugins I have used most often, though there are others available for these source control vendors and others not included:
Tip 2: Start Every Day Fresh
Agile methodologies that include continuous integration strongly advocate that source control be directly integrated within the IDE, as is achieved by using a plugin for source control. Without this integration, many developers tend to let their local environment become out of sync with the full project source. All it takes is for a developer to miss a one-method signature change before checking in dependent code to lead to an all-night debug session.
Starting every day by getting the latest code from source control won't eliminate the need to chase down the results of a missed change, but it will greatly reduce both the frequency and impact of missed changes. You can also go one step further and get the latest of all code that is related to anything you are working on at the time you begin working on it. This way, you actually can completely eliminate this potential pitfall.
Tip 3: Never Put Off to Tomorrow What You Can Check In Now
After you and your team have developed the habit of getting the last code at least daily, things can go wrong only when the latest code isn't in source control. Just as the ancient computing phrase "garbage in, garbage out" is still true, the more esoteric phrase "you get back what you put out" still relates to software development. So if you are getting the latest from source control at the start of every day (or more), you should check in the latest source at the end of every day (or more). The best habit is to check in code every time it both compiles and unit tests without breaking anything.
At the very least, everything should be checked in before logging off for the day. Many developers use the excuse that something is incomplete and cannot be checked in, but if the code changes are so sweeping that the incomplete code cannot be either commented out or saved locally to a temporary file while the original code is rolled back, then the odds are very good that the code has also become out of sync with the full project source (or will become so soon). The "not done yet" excuse has resulted in developers becoming days out of sync with the project, and almost always takes a long time to integrate back in.
And not to be too morbid, but there is also the "what happens if you don't show up for work because you [enter unpleasant scenario here]" consideration. Being courteous about source control is just as important as other courtesies.
Tip 4: Use Check-in Comments
I admit, this is a habit I need to work on myself. While it is easy to think "if someone wants to know what changed they can just run a diff," the truth is that it is much easier for them to just read the comment that the previous developer courteously added when they checked in their changes. Also, the value of the check-in comment is not so much for the one version change, it is often a huge time saver when you go back five or six iterations and wonder why you yourself made a particular change.
Tip 5: Choose the Best Merge Strategy for Your Team
As I mentioned in the first tip, I used VSS in my early days of using Eclipse. On one project there were a couple of new team members who had previously done most of their source control with CVS. The term "check out" has entirely different meanings between those two products. In VSS, it means taking control of the code, which results in the file being locked so that others don't make changes at the same time. In CVS it means getting the latest version of the code from source.
One of the team members with CVS habits thought he was doing exactly as suggested in tip #2 by "checking out" the entire project at the start of the day, and then proceeding to make a large number of changes as part of a proof-of-concept approach. When other team members noticed that all the files were locked by the same person they asked him to check the code back in. Which he did -- all of it, including his changes.
It took two days before the project was restored to its previous functional state.
While some products are like VSS, where only one developer can make changes at a time, many products allow multiple developers to make changes simultaneously and then merge the changes together. In the anecdote above, this merge approach would not have worked because the code style of some developers were too divergent from others (which is why it took so long to recover the project).
Some development teams are perfectly in sync with their code styles and continuous communication. For them, doing a merge when they check in their source is a perfect strategy for productivity. This is not true of every team, however. Which is why most of the source control products that allow merging also include the option of turning that feature off, or at least a method to lock a file manually (SVN prompts for a lock comment too, which is actually a good idea). Your team should decide whether merging is a productive approach or not, and then stick to that strategy for the duration of the project.
Tip 6: What Not to Put in Source Control
There are some files in Eclipse projects that do not belong in source control. These files (and entire paths) vary from project type to project type and even more so when you consider all of the vendor-specific versions of Eclipse that are available. There are two simple tests to apply to a file or folder that will cover the majority of projects and vendor versions.
- For Eclipse project configuration files, Does it contain machine-specific values? If it does, it usually should not be in source control. Most configuration files generated by Eclipse use variables that are configured at an IDE level so that the file is portable.
- If the file is generated on every build, the file can usually be eliminated and forgotten about by simply turning off automatic builds and running a clean prior to adding new files to source control. There are some exceptions, such as the
.build path, which is emptied but still present after a clean. The
.build path never needs to be in source control.
Tip 7: Have a Build Master or Automate Continuous Integration with Larger Teams
While following the first six tips will keep many teams from ever experiencing source control-related issues, there are times when even the most conscientious team members make a mistake or forget to do something. On small teams, following the earlier tips will usually allow the issue to be found and fixed before it causes any real distress. For larger teams, though, it is better to have a way to make sure things don't get too far out of whack and lead to wasted time and lost weekends while tracking down an erroneous bug.
One way to stay on track is to establish the Build Master role and include as a task for that role regular builds (daily, if not more often). The other solution is an automated continuous integration product. There are many such products, and evaluating them could (and may) fill an entire article in itself. Suffice it to say that if your project needs one, it is worth the effort to choose and configure one.
Every developer knows that source control is a necessary part of every project. Now that you have read this article, you have some pointers that not every developer knows -- or at least practices. Hopefully this knowledge leads you to fewer issues and greater productivity.
About the Author
Scott Nelson plays the roles of developer, architect, project manager, server administrator and portal evangelist on any given day, and blogs lessons learned at Head in the Web when it is not suitable for Developer.com articles.