Salvatore Iovene

Ver­sion­ing sys­tems like CVS, SVN or Darcs are very impor­tant tools, that no seri­ous pro­gram­mers can omit to use. If you started a project with­out using any ver­sion­ing tools, I really rec­om­mend that you start using one imme­di­ately; but I’m not dis­cussing this right now.

I would like to point your atten­tion to some best prac­tices that I rec­om­mend when work­ing in a team.

1. Don’t use ver­sion­ing like it were a backup tool.

   I’ve heard this ques­tion too often: “Have you put your code safely on SVN?”. That’s a bad ques­tion. Stor­ing code to an SVN server is not meant for safety, i.e. for fear of los­ing it. You are talk­ing about some­thing else, and that’s called backup. Take Darcs, a not so pop­u­lar ver­sion­ing sys­tem. It can start with­out a server, and you can just run it locally on your machine with­out launch­ing any dae­mon what­so­ever. A faulty hard drive can still make you lose all your work, of course. That’s why you have to do back­ups, of course, but they don’t have any­thing to do with ver­sion­ing. Hence, com­mit­ting to the repos­i­tory once a day, before tak­ing off home, e.g., is not an accept­able prac­tice, espe­cially if you work in a team. Doing that would be like mak­ing a daily backup. An SVN com­mit, instead, has to have a mean­ing of some sort, not just “Ok, let’s store to the SVN server the work of today”. More­over, some­times, if the sched­ule is tough and the coöper­a­tion is tight, you need to com­mit very often so your peer will keep up with you all the time, and not just find out, at evening, that he’s got dozens con­flicts after check­ing out your code.

2. Com­mit as soon as your changes makes a log­i­cal unit.

   How often should you com­mit? Theres no such thing as com­mit­ting too often, or too rarely. You should com­mit each time your changes rep­re­sent a log­i­cal unit, i.e. some­thing that makes sense. Usu­ally that hap­pens because you’re fol­low­ing a plan, when cod­ing (because you are, aren’t you?). So, you find out a bug in the trunk, plan a strat­egy about how to fix it, fix it, and then com­mit. This makes sense because that’s a com­mit that fixes a bug. So that revi­sion X is buggy, while revi­sion X+1 is not. Don’t be shy about com­mit­ting too often. Should you just find an insignif­i­cant typo in a debug string, or in a com­ment, don’t be afraid of com­mit­ting just to fix that. Nobody will be mad at you for being pre­cise. Con­sider the extreme sit­u­a­tion in which, after months and months, you may want to remem­ber “What was the revi­sion where I fixed that typo in that debug string?”. If you ded­i­cated one signle com­mit for the actual finite log­i­cal unit of cor­rect­ing the typo, you can just scroll back your changelog and find it. But what often hap­pens, is that peo­ple will be doing some­thing else, and, while doing that some­thing else, will notice the type, and cor­rect it, and basi­cally merge that cor­rec­tion with the rest of the com­mit, mak­ing that thing los­ing vis­i­bil­ity. To make it sim­ple: your SVN com­ments shouldn’t explain that you did more than one thing. If your SVN com­ment looks like “Fix­ing bugs #1234 and #1235″ or “Fix­ing bug #4321 and cor­rect­ing typo in debug sting” then you should’ve used two commits.

3. Be pre­cise and exhaus­tive in your com­mit com­ments.

   The sec­ond most annoy­ing thing ever is com­mit­ting with blank com­ments. If you’re work­ing in a team, your peer devel­op­ers will be frus­trated about it and pos­si­bly mad at you, or will label you in a bad way; pos­si­bly pub­licly humil­i­ate you. If you’re work­ing alone, you will expe­ri­ence what you’re hypo­thet­i­cal devel­op­ment com­pan­ions would have: frus­tra­tion in not being able to eas­ily track down what a cer­tain com­mit did. Com­ments in com­mits are impor­tant. Please be pre­cise and explain in detail every­thing you did. In the opti­mal case, I shouldn’t need to read your code.

4. Never ever break the trunk.

   This is prob­a­bly the most annoy­ing thing when deal­ing with peo­ple who can’t use ver­sion­ing. Break­ing the trunk is an habit that will quickly earn you the hatred of your col­leagues. Think about it: if you com­mit a patch that breaks the trunk, and then I check it out, what am I going to do? The project won’t build so I either have to fix it, or come to your desk and com­plain to you. In both cases I’m wast­ing some time. And con­sider the first case again: what should I do after fix­ing your bro­ken code? Com­mit it? Send­ing you a diff? If I’ll com­mit, chances are that you’ll have con­flicts when you check­out, and you’ll have to waste time in resolv­ing them. Maybe send­ing you a patch would be the best way, but still it’s a waste of time for the both of us. So the thing is: before com­mit­ting, ALWAYS dou­ble check! Make a clean build and make sure that it builds. And don’t for­get to add files! It’s a very com­mon mis­take: com­mit­ting good code, but for­get­ting to add a file. You won’t real­ize, because the thing builds, but when I’ll check­out, I’ll have trou­bles, because of miss­ing file(s). If you’re using Darcs, just make a “darcs get” in a new direc­tory, and then build.

5. Branch only if needed.

   There are some ways to han­dle branches, but here’s my favorite. The most of the work should hap­pen in the trunk, which is always sane, as stated by the pre­vi­ous prac­tice, and the patches should always be small, so that they can be reviewed very eas­ily. If you find your­self in the sit­u­a­tion of need­ing to write a large patch, then you should branch it. In that way you can have small patches that will break your branch over the time, but they can be eas­ily reviewed. After the process is com­pleted, i.e. you’ve achieved your goal of fix­ing a bug or imple­ment­ing a new fea­ture, you can test the branch thor­oughly, and then merge it to the trunk.