Whom is this for?

I am writing this guide for students taking the Software Engineering module (IS203) at Singapore Management University. If you’re not part of this target audience, some of the information may be applicable to you but I wouldn’t count on it. Although most of the tips are going to be very general, I’m going to assume usage of Tortoise SVN and the NetBeans IDE as that is what I use. That being said, this is not a step-by-step guide and you will be expected to understand the basics of using Tortoise, which you should if you were in class.

First things first

Setting up is pretty important in order to collaborate on a group project. Create an empty folder and import it into your group repository; the repository is a holding place where your codes go. Delete it and check it out again. This is now your working copy and any changes you make in it can be committed back to the repository.

Next, create your project in NetBeans in this working folder and run it. A quick look in the folder reveals that a lot of files have been generated and that’s the good thing about NetBeans. However, there are some things that shouldn’t be put into the repository. The repository should store source code and as best as possible nothing else. However, we now have three folders that we don’t want in our repository.

Before we do anything else, we will want to set the Subversion ignore property on the folders build, dist and nbproject. We don’t want files that are always regenerated and development environment properties in the repository. Once you’ve set that property, commit the changes and the new project files now. If you don’t know how to set the ignore property on a folder, google it.

Continuous Integration

The easiest way to prevent integration problems is to not integrate at all. Or at least, not in the way that software developers used to. Instead, we should strive to develop a process where source code is always integrated through frequent updating and committing.

Developers should be working on the latest codes where possible; the ability to test your working code against the latest code base reduces rework and bugs. Subversion makes this possible by allowing you to update and commit as often as you want without having to transfer file manually. And you will want to do so regularly.

When to update

You should update your code, before you start work, before testing and before committing. By updating before you start work, you won’t be working with code that is out of sync, so you are always writing code you know will work with the latest code. By updating before testing, you won’t be testing your working codes against outdated codes, which would be pointless since the code base might have changed by then and your test results are pretty much useless. Lastly, updating before committing limits the possibility that you check in code that may break the build.

This last point is of paramount importance. If Developer A submitted has submitted changes to the repository that Developer B is unaware of (because he did not update), Developer B will commit code that may not work as intended, or worse still, not even compile. Not only that, if the project manager decides to revert a project’s status backwards, he should avoid this revision simply because it doesn’t compile. However, since Subversion does not tell you which revision compiles or not, or what bugs it might have the project manager may revert to it anyway, wasting time and inducing confusion. Your commit must not break the build.

When to commit

Commit early, commit often, commit in small amounts.

Learn this mantra, practice it and never forget it. Consider this scenario, a developer is working on a new feature but does not wish for others to see his code, because it is a little buggy and messy. His codes exist in his working copy for a month before he decides to commit and when he does, the commit log shows that he has made changes to more than a dozen files. Because his work was split over the course of the month, he forgot what exactly was done and half-heartedly comments so in the log. Let us assume that this developer understood the importance of updating often, tested his changes with the latest code base, and thus did not break the build.

However, this is still bad because while he kept his codes in the working copy, it existed in a vacuum and nobody knew anything about it. This is called a code bomb and introducing so many changes to the code base makes other developers suspicious, especially if such changes affected the behaviour of code that they were dependent on. Because so many files were changed, it is hard to define how the entire code base was changed and in what ways it affected the system.

This causes a major disruption to the workflow of the other developers as they now have to review their development plan and how they might have to adjust to the changes.

Any Resistance?

You might be thinking that it will be more problematic if you keep updating, because you can’t get your codes to work and if other developers keep changing their codes, it will be impossible for you ever get it done. Plus, handling conflicts is additional work that you don’t need now.

Well, your fears are actually quite valid. However, if other developers are following this guide as well, there will be no code bombs and commits made by others should be easily understood and explained in the log if not in comments in the code. Such adverse effects should be kept to a minimum.

You may also be quick to point out that I am contradicting myself when I say that we should not check in code that doesn’t work while at the same time I emphasized on committing often. How can you check in code if it doesn’t work? The answer is to change your coding style. The style where you paste a lot of code in and hope it works. You didn’t really think it would work now did you?

Do the simplest thing that works, test it, retrieve updates from the repository, test again, commit and repeat.

If you are able to follow this flow closely with your team, expect a smoother development process for the whole team. This is a best practice that we should all strive towards.

Conclusion

Keeping to these guidelines will pay off in the long run. For some, changing the way we write code can be difficult and you might brush this guide off. Well if you do so tell me so that I can write a case study about you when we finish the project. You can expect to do more work (or rework) than my group if you aren’t following best practices.

Feel free to share this article with your team and other teams if you’re not that competitive after all. I only request that you link to this page as the original source. If you find any errors or completely disagree with me, email me. Good luck with your project!