Fans of Marvel movies know to wait around until the end of the credits to see the extra scene. This adds a bit of time to the theater experience, as the credits go on for quite some time; it takes hundreds of people to make a movie on that scale.
At work, I’m one of a dozen developers on my team and one of several thousand developers in the company. While each team largely sets its own policies, there are some general standards for consistency across the company.
Even relatively small side projects tend to involve several people. I’m currently finishing a small computer science textbook that I’ve been working on for the last few years. Even though I have a PhD, work experience in both writing and editing, and a tendency to do everything myself, my book still has a technical editor, a copy editor, and a graphic designer. I could certainly finish the book without any of those people, but they’ll help me to make it as good as it can be.
In short, any project of significant complexity, even if it’s small enough to be done by one person, will benefit from having multiple sets of eyes. When multiple people are working on the same content, however, it’s important to have standards for consistency and for resolving disagreements. Sometimes this means there’s one person in charge – the director, the lead developer, the author – who makes decisions that the rest of the team will follow. Sometimes it’s a collaborative process. But consistency is key.
What are some things to do to help ensure that your projects are successful?
1. Save frequently and use version control.
Not too long ago, I needed to retrieve some code that had been deleted by another developer who had left the company over a year before. Although the code never made it to production, I was still able to retrieve it from svn, which saved me dozens of hours of work.
1a. Make small commits with good comments.
In the past, my habit was to save when I finished a chunk of development or at the end of the day, whichever came first. That meant that even if a disaster occurred I wouldn’t lose more than a day’s work, but it also meant that my svn commits while working on a project tended to be rather large and contain a number of fixes, making it more difficult to locate a specific change. Now, I generally commit (with a descriptive svn comment) every time I fix one bug or add one new feature. The primary reason for this is so that when I go on to the next change, if I screw it up it’s easy to roll back to the last stable state without losing any of my previous work, but it will also make it easier for any future developer (including future me) to find a specific fix if needed.
1b. Delete commented-out code.
I’m not opposed to comments – I’m in the school that believes that what the code is doing should generally be clear from reading it, but comments are useful to explain why the code is doing what it’s doing and document any assumptions. When working it’s easy to comment out sections of code for testing or because they’re not currently needed, but leaving those in afterwards clutters up the code and makes it more difficult to tell if something should have been turned back on. Version control means not needing to keep commented-out code. Just delete it – it can be restored if it’s needed again in the future.
2. Have consistent standards.
There are a lot of areas where there are multiple ways to do something and it doesn’t really matter which one you pick, but being consistent in your choice makes things easier. For example, my team consistently puts the list of properties for a class at the bottom of that class; while it’s easy enough to use F12 to jump to a given property definition, having all the properties together in the same place in each class makes it easier to look through them when needed, without having to think about it.
3. Use good names.
Few things result in as much unneeded mental effort as deciphering code with unclear or misleading variable names. I’ve certainly had instances where towards the beginning of a decent-sized project I’ve given two properties similar names and by the end I’m having trouble remembering which is which. If it’s not clear what information a variable or property is holding, then the name needs to be updated! Similarly, function names should accurately describe what the function does.
4. Test everything that needs to be tested.
What I’ve struggled with the most as a developer is making sure to test all the things that could possibly go wrong with my code. Unit tests can do a big chunk of the actual testing, but the developer still needs to come up with the test cases. This can be a challenge because as the developer you (hopefully) understand how the code is supposed to work, so you use it correctly. Take the time to figure out all the logic-impaired things your users might do and try those also.
5. Understand the desired outcome.
When I’ve had development that’s gone way over the expected timelines, it’s been because requirements have changed repeatedly over the course of writing the code. While that is sometimes unavoidable, do try to minimize it as much as possible for larger projects by writing a reasonably complete design document and getting buy-in from the relevant people before you start development. Sometimes you even get lucky; I’ve had projects end up becoming much less complex before I ever started coding, because my initial design was more complicated than it needed to be and my design reviewers were able to point out a better way to accomplish the same task. Aside from getting buy-in from key people, a good design helps you be sure that you understand the requirements, which makes it easier to implement them correctly.
It’s always worthwhile to make things easier for the next person who will look at your code. Very often, that person is you.
