Carpenters have a saying “measure twice, cut once”. The idea is that if you double-check your work, you are less likely to make mistakes, and have to re-do the work later. A former boss adapted this to software development – “diff twice, commit once”. That is, before you commit a change, take a second look at what you are about to change. I have sometimes rephrased this to “slow down to speed up”. There have been a number of times in my career where I have been working on projects which had tight deadlines, and there was a lot of pressure from management to get things done quickly. In order to meet these tight deadlines, we would cut corners. One of the frequent strategies was to reduce the amount of testing we were doing. Instead of thoroughly testing a new feature, we would just release it. In many cases, this led to more bugs, which took more time to fix. By trying to do things more quickly, we ended up needing more time in the long run. On top of that, this sort of working is also very stressful.
Another former boss of mine once wrote a simple idea in a presentation he was giving about transforming our organization:
Know what you are doing
Geert-Jan Kruijff
This seems like a trivial and obvious thing to say, but I have frequently witnessed people just trying things out without really understanding what they were doing. I have been guilty of it myself. Often times, software developers are partially to blame for this situation. When a new technology is developed, (let’s call it X) it usually requires a great level of expertise to actually use it. One must specify all the correct parameters and options and such in order to get it to what you want it to do. Frequently what happens next is that someone writes some wrapper code around X, which sets a bunch of the parameters to ones that they like to use, and then they release this new tool to their team; let’s call that Y. Now people learn how to use Y, but when something goes wrong, they don’t understand how X works, and then have to ask the developer of Y for help. There are obvious trade-offs to these approaches. Making tools easier to use is a good thing in many cases, but it is also really helpful to know what is going on under the hood.
Source content management (version control) tips
I’d like to give a few tips I have found helpful over the years to making fewer mistakes when committing code.
Don’t use -m
If you work from the command line like I do, most version control systems like svn and git have a -m option which allows you to specify a commit message on the command line. I have seen many tutorials using this option. I highly advise against it! Why should you not use -m?
- It encourages you to write a poor commit message. If you don’t use -m , then a full text editor (of your choice) will be opened, where you can write a meaningful commit message about your changes. This is the place to include high-level comments, meaningful context, links to bug reports etc. Your colleagues (and your future self) will thank you for writing a meaningful message and not just something like “fixed bug”.
- When your full editor gets opened, it lists all the changes that are about to be committed. This gives you another chance to double-check whether or not what you are about to commit is what you really intend to commit.
Commit specific files or directories
Instead of simply doing svn commit, which will commit all changes recursively under the directory you are currently working in, pick and choose which files or subdirectories you want to include. This takes a little bit more time typing, but will avoid mistakes. Along this thread, if you are using git, do not use git commit -a, which will also include all changes. Instead, pick and choose the changes you want to do include by using git add <filename(s)>. There is one other potential gotcha with git. In git, you can commit certain changesets. So let’s say that you edit file x.txt, then you issue git add x.txt to stage your changes. Then you remember that there was one more change you wanted to put in, so you edit x.txt one more time. Then you run git commit. You are not going to commit that last change you made, but rather only the changes up to the point when you ran git add. You can see evidence of this when you go to write your commit message. If you are committing all changes to a file, that file will only show up in the list of changes to be committed. If you have further changes which you have made after running git add , then the file will also show up in the list of changes not to be committed (this may be in fact what you want to do in some cases, but in most cases it probably is not).