Always write software as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
Write code collaboratively
By Dominik Wilkowski
A coding style guide
The most important thing when working on a team is communication. People need to be able to work together effectively and the only way to do that is by communicating. As developers, we communicate primarily through code. We communicate with other parts of the software through code and we communicate with other developers through code.
While the software your code communicates with doesn’t care how the code looks, the other developers on your team certainly do. The way code looks adds to our understanding of it. How many times have you opened up a piece of code that somebody else wrote, and, before doing anything else, re-indented it the way that you like? That’s your brain not being able to figure out the code because of how it looks. When everyone is writing code that looks different, everyone is constantly trying to visually parse the code before being able to understand it. When everyone is writing code that looks the same, your brain can relax a bit as the understanding comes faster.
Writing code against a style guide outsources information into the code itself. When you decide when and where to use comments, as well as which patterns should and shouldn’t be used, you are leaving a breadcrumb trail for your other collaborators to find their way back to the meaning of the code. Code is incredibly hard to understand for anyone if it has a very different style to what we are used to and it will take a solid amount of effort to understand and retrace its working before we can start making changes.
What’s in a style guide?
- How and when to use comments
- How to indent your code
- Appropriate use of white space
- Naming conventions for variables and methods
- Code organization/architecture
- Patterns vs anti-patterns
- How we modulate
- ... etc
Find what’s wrong, faster
One of the biggest reasons to have a coherent style guide is to help make errors more obvious. Style guides do this by acclimating developers to certain patterns. Once you’re acclimated, unfamiliar patterns jump out of the code when you look at it. Unfamiliar patterns aren’t always errors, but they definitely require a closer look to make sure that nothing is amiss.
When you have a style guide, code that otherwise seems innocuous immediately raises a flag because the style isn’t followed. This is one of the most overlooked aspects of style guides: by defining what correct code looks like, you are more easily able to identify incorrect code and therefore potential bugs before they happen.
Reduce the need for rewrites
Many times when we disagree with a piece of code we feel like we should redo what has been done to make it easier for the next person to handle it. The problem here is that often times the next person thinks the very same thing about your code and redoes your code and so on. By us agreeing to one style we take this problem head-on. We know what to expect before opening the file and diving in.
Ok, let’s create one
It’s important that everybody on the team participates in creating the style guide so there are no misunderstandings. Everyone has to buy in for it to be effective, and that starts by letting everyone contribute to its creation. Make sure everyone understands that a style guide is not one persons opinion but a set of rules everyone agrees with. Don’t get too worked up about the details, it’s more important to agree to one style.
Beyond style guides
Versioning systems enable us to collaborate with many other coders but it can get messy quickly and mess up our commit-logs. GitFlow is a branching model for Git, created by Vincent Driessen. It has attracted a lot of attention because it is very well suited to collaboration and scaling the development team. Please read about it here.