Correct Usage of Source Code Control Software

Source Code Control (SCC), everyone probably used it or abuse it. As a new developer 2 years ago, I was assigned to a project, it was my first time being in a project and coincidently it was also the first time most of the project members were using SVN (They mostly use Visual Source Safe 6). So here are some of the issues that I think are relavant for "newbies" like me to SCC. I am not going to talk about specifics like actually how to do things like checking in and out code,  as there are many resources on the web that cover the same thing.

1. RTFM

Each source code control has it's own benefits and idiosyncrasies that we all have to live with. Read the manual on not just how to do things like commit and update. But also how to do branching, tagging and merging of source codes and most importantly how to roll back.

Don't try to "cheat" the source code control unless you know what you are doing. Like when i first use Visual Studio 2005, we use Visual Source Safe (VSS) 6 as the SCC because of the integration between VS and VSS. But Visual Studio had one annoying feature, it must be connected to the VSS server in order to work properly. So if we unplug our developement machine from the network and start up Visual Studio, it sorts of "hanged" while trying to connect to VSS. It can't really something like SVN where you can just update, unplug  and work on you code then commit it. VSS requires you to "check out" the file so others can't use it, the way it makes the other users not able to write to it is by setting the "read only" flag on the file. So we had a developer who needs to work offline and we had a lot of trouble getting all the files in the SCC in sync and that developer had to manually change the "read only" flag to allow us to write code, but when the actual owner checks in all the changes are replaced again. And when we were on a dead line rushing code out, trying to handle these problems was just time consuming.

2. Source Code control is for source code!

I remember that when I first learnt java in school, it was with emacs as the editor and batch files for compiling. Now we have super IDE's like Netbeans and Eclipse that has nice syntax highlighting and even javadoc help built in.

We had a problem using Eclipse and SVN together,  the problem was that most modern ide's they tend to have some custom folders/file that they use to store some of the ide's customization like where are the javadocs located, the jdk/jre location, some font and color settings and so on. Imagine that you created you own beautiful environment and you check in those settings to the source code control, and you team member also check in his customizations. Imagine the havoc when you update the files and found that the jdk is pointing at a wrong directory and the classpaths were all wrong. My project that time we had a lot of problems trying to get all these sorted out and it plainly just waste time. So don't waste time like me just do the following.

So remember Source Code Control software is just that use it for source code. Check in only the source code (src/test) not the compiled binaries directory, not the .nbproject / .metadata directories just the code.

You might want to have a structure for storing the code, a common one is

src is for source, test is for unit tests files and lib is for the libraries that you are using. Thats probably the most basic directories that you will need.

Whether you will use source code control for storing your libraries is up to how your project wants to manage it. There are people who use tools like Maven to handle the dependencies. My work set-up is such that the development network and the internet are not connected, so for Maven to work, we will probably need to set up some kind of local repository and we haven gotten down to that or really see the need for that yet. For now we just commit the dependencies into the SVN. We did not encounter much issues, except we must be care not to introduce versions of the same libraries with different names (e.g log4j-1.2.10.jar and log4j-1.2.15.jar in the same directory, so which one is the one we are using?) into the build.

3. Read about how people organize their code and learn best practices.


Learn about the best practices in using that particular source code control software, and how to organize/manage your code like creating trunk, branches and tags. Learn how to branch out you code to do modifications/test concepts and then merging it back to the main source tree. Learn how to version software using tags, so that you will have some sort of a release tree that you can keep track of the code at various stages. I recommend reading Pragmatic Programmers series of books on version control.

Afterthought

For new programmers it pays to know a bit about more about SCC software and how to mange source code, I don't think they really cover this at school (I know mine didn't but that was some time ago). So it good to read an play around even for you own personal projects. Source codes are the fruit of every programmers work so don't let managing it or using SCC software be a bottleneck or even the source of fustration in your work.