There are many ways to produce software. Over the years of producing client and internal projects, we’ve tried out many different techniques. We have established guidelines to follow that have made us better developers.
Use version control
A version control system keeps track of all source code, logging each change, who changed it, when they changed it, and why they changed it. This logging is invaluable. We’ve used Subversion, Darcs, and Git, each having their own set of pros and cons.
With version control, we can look up who last changed a piece of code and read the commit message to see why they did it (more on this later). Version control systems help merge different changes to a file, so we can work in parallel with confidence that our work won’t be lost. We use the branching features to make large, multi-week changes to code without sacrificing the ability to make quick bug fixes to the production code. We use tagging features to take snapshots so we know exactly what state of code is running on the live site at any time.
Use a ticket system
Ticket systems are a vital project management tool to keep development running smoothly. Years ago we wrote our own ticket system, then realized we could get a vastly better product using one of the many free options. We settled on Trac. Trac helps us assign tasks to our staff, sends email notifications so we know when something has changed, and serves as a clearing house for task-related information that was previously locked up in someone’s email. We use the system to keep up with low-priority tasks that would previously get forgotten in old email. It also helps us communicate, using ticket comments to ask and answer questions without needing to disturb each other.
Keep track of your time
Time tracking is a key to making decent estimates. You need a feedback cycle to see how accurate your estimates were, and adjust from there. Time tracking is essential to accurately generating billable hours. Even on non-billable work, when the financial motive is gone, it’s important to get a sense of how long a task will take you.
Make your version control and ticket system talk to each other
The unnecessary overhead of a ticket system can be eliminated completely by linking it to your version control. Every version control system provides hooks for you to run scripts after every commit. We use that feature to automatically add comments and time to tickets from the commit message. This gives developers one easy place to record their notes, and encourages good detailed commit messages.
Write good commit messages
Commit messages is the way to tell the future what you were thinking when you changed this code.
Take the extra time and ask yourself:
- Does the commit message give you (and everyone else) a reasonable idea of what has actually changed?
- Does the commit message use unidentified pronouns?
- Do you reference a relevant ticket number?
- Do your commit messages contain enough nouns such that you could search logs in a month and find these commits?
- If you are debugging this change 2 years from now at 11:45PM, will it make you angry?
Write human-readable code
Use descriptive names. The short-term benefit of using short names is drastically outweighed by the long-term maintenance cost you pay every time you come back to a piece of code and wonder what the variable “A1” has in it. With the exception of looping variables, long names are better. Use editors that support code-completion, so length and spelling isn’t an issue. With descriptive names, you don’t need to comment as much. Comments quickly become stale and inaccurate, but your code will always represent the current process.
Simpler is better
Log. Log a lot.
Get a second opinion
Code reviews and team programming are easy ways to improve code and reduce defects. After writing a section of code, print it out and talk about it over lunch. When fighting fires in emergency situations, having someone there helps prevent panic reactions. When writing new code, the extra person is an automatic sanity check. Full on pair programming isn’t always required, but can really help when working on critical code (eg: anything involving money). Short of pair programming is a quick impromptu consult, where you lay out what you’re about to code and get a second opinion. Frequently the other person can see a simpler solution because they haven’t been focusing on the problem for an hour, and the process of explaining your plan can provide insight.
