Tortoise more than just version control
August 24th 2009 | Jimmy Bosse
For most developers version control, or source control, is a minimum requirement. The primary purpose of version control is to enable multiple team members to work in the code without stepping on one another’s toes. It is also great for branching (creating a new direction in the code that may or may not be integrated back in to trunk) and tagging (marking a particular snapshot of the code, such as a release).
Our Subversion Repository is the ultimate code documentation.
Using source control as documentation is a whole lot better than placing comments inside your code. If you need to write a comment to explain what your code does, then its logic probably needs simplifying. Well-commented commit notes, on the other hand, remind you exactly what you were thinking when you first committed that code.
- Good commit notes contain four important elements:
- An explanation: WHY? Explain why you are writing the code.
- The Identity of the Writer. We use the initials of the pair committing the code.
- Story Number. An identifier linking the commit to the user story it is implementing.
- A Summary. Brief notes about what you are trying to achieve in the code you are submitting.
The most important one is WHY.
We frequently find ourselves looking at a block of code and trying to figure out why it’s there. The longer a piece of code remains in a codebase, the greater the chance you’ll forget why it was written in the first place. If good commit notes were written, the “blame” feature becomes your best friend. Its name is misleading as it implies that its purpose is to reveal the culprit who broke something, but in fact it is intended to remind you who wrote the code, and the purpose for which they wrote it. If you are fortunate enough to have a repository for your user stories, you’ll always have a sense of the bigger picture at the time the code was written.
As you work on a software project, your understanding of the problem evolves, as does your approach to the solution. Something that is obvious and finely-crafted today might look like a silly hack to you six months from now.
Leave your future self a note as to how awesome you thought you were at the time. You’ll thank yourself for it—and so will your team members.
Jimmy Bosse is a Team Lead at Thycotic Software, an agile software services and product development company based in Washington DC. Secret Server is our flagship password management software product.
Comments
Leave a Reply
