It’s a common misconception that software developers create source code that tells a computer what they would like the computer to do. Well, obviously, that’s a part of the job, but in reality, it’s just as important (if not more important) to consider that the purpose of the source code that we create is to communicate our intentions to the other software developers who will follow us to maintain, improve, and otherwise work with what we’ve left behind for them.
Once your code exists in valid syntax for the language that you’re working in, the compiler or interpreter that makes sense of what you’ve written is equally happy if you send it:
if (fPlugins) {/* connect to our new source of data. */
fPlugins->addChangeListener(this); if (fPlugins->Size() != fSlots.size())
{fSlots.clear(); for (int i = 0; i < fPlugins->Size(); ++i) {
PluginSlotComponent* slot = new PluginSlotComponent(fPlugins, i);
fSlots.add(slot); this->addAndMakeVisible(slot); } } }
as it would be to encounter:
if (fPlugins)
{
/* connect to our new source of data. */
fPlugins->addChangeListener(this);
if (fPlugins->Size() != fSlots.size())
{
fSlots.clear();
for (int i = 0; i < fPlugins->Size(); ++i)
{
PluginSlotComponent* slot = new PluginSlotComponent(fPlugins, i);
fSlots.add(slot);
this->addAndMakeVisible(slot);
}
}
}
Even if you’ve never seen a single line of C++ code before (but having read English text) it’s probably immediately apparent that the second example is going to be easier for another developer (or the original developer coming back to this after some period of time) is going to be able to make sense of the second example more easily — it should be clear that there’s a level of organization from top to bottom, as well as another level of organization that’s represented by indentation.
If either of those work the same, though, who cares what the code looks like?
A Place for Everything, and Everything in its Place
Unless a project is only going to ever be worked on by a single developer (in which case, however she likes to write code is the de facto style for that project), anything that can be done to reduce the effort needed to get a new developer working successfully inside that codebase is effort well spent. As a new developer, it’s more useful to spend time learning what the code is doing, not figuring out random idiosyncracies of how the preceding developer or developers liked to do things.
Factors to consider here include things like:
- When and how much do blocks of code get indented?
- How do you indent — using spaces or tab characters?
- How long is okay for a single line of code to get before you wrap it somehow?
- How do you format wrapped lines of code?
- How much documentation or comments is desired or appropriate?
- What’s valued when naming things: terseness, or descriptiveness?
Sometimes we encounter code that’s been touched over its life by dozens of develoeprs, each one with their own strong and non-overlapping opinions on each of those topics, to the point where it almost looks like a ransom note made from letters cut out from a newspaper.
By ensuring that the formatting of code and the patterns used to name things are sensible and consistent, a developer wastes less time thinking about those things (because they quickly become habit) and a maintenance programmer wastes less time trying to disentangle the meaning of a piece of code from its garbled presentation.
Find and Kill Those Bugs
The other advantage of sensible code style consistently applies is that there are classes of bugs that are made more detectable by the naked eye. "Wrong" code often just looks wrong, or at least wrong enough that it sticks out enough to get a second look at the underlying logic.
An example of this comes from languages like C, C++, and Java. A developer wants to do something when a certain condition is true (and you shouldn’t need to have ever seen source code before to follow along here), like:
if (someCondition)
doSomething();
Sometime later, there are a few other things that should also happen when that contition is true, so someone adds them:
if (someCondition)
doSomething();
doAnotherThing();
doFinalThing();
The programmer here clearly indends the visual grouping of those additional steps to only happen when someCondition is true, but that’s not how the language interprets things. When you have a single thing following that if() statement (our original example just above), you can either surround that thing in a pair of {} characters or not. The problem is that when you want to include multiple things controlled by the condition in the if(), the curly braces suddenly become very important — in the example here, the doAnotherThing() and doFinalThing() functions will always be executed no matter whether someCondition is true or not.
This is why many style guides (including ours) require that curly braces are always used in this case — we take away the opportunity to make the mistake in the first place, and by becoming comfortable with the convention, the error jumps out quickly. A developer seeing that code in the wild would:
- Take some time to study the code and verify that the intent there really is that the intent of the code matches the visual grouping from indention.
- Modify the code with correct placement of curly braces surrounding the block.
- Test to verify that the original programmer’s intent was in fact correct.
if (someCondition)
{
doSomething();
doAnotherThing();
doFinalThing();
}
Follow the Research
At a certain level, it’s more important to have an agreed upon set of conventions that a team follows, than the details of what those conventions actually are. The importance of a standard isn’t so much that it’s right as that it’s standard.
That being said, academic Computer Scientists have expended no small effort researching how these kinds of practices affect the ability of developers to spot defects and keep them from introducing defects in the first place.
Learning more about what is known empirically about programming style can help avoid turning the creation of a programming style guide into a never-ending emotional argument. If you’ve never heard programmers argue about the One True Way that braces should be placed or code should be indented, consider yourself lucky. Mcuh better to have someone look at the research and find that someone else has already gathered data indicating that once code blocks are indented more than four spaces per level, defect counts start rising.
It’s interesting lately to see that there are languages that are choosing to tightly couple their language definition to programming style issues. For example, the example just above can’t be reproduced in the Python language; in Python, indentation is used to indicate the kind of blocks that we needed curly braces to correct here. This is one of many reasons that my Python code tends to work correctly right away and continues working correctly. Google’s recent ‘Go’ language has an official style that’s enforced with a formatting tool that’s provided as part of the compiler suite.
Not Enough By Itself
A well-considered and consistent set of coding conventions are necessary, but not sufficient, for the creation of a solid software project. It’s possible for weak or inexperienced programmers to follow a set of formatting rules perfectly and generate buggy, unusable software. Having looked at a lot of source code in my career, I’ve also seen a certain amount of code that worked just fine, at least in the hands of the original developer, but were incredibly difficult to understand or work with for anyone else. The rise of Open Source software development seems to have cut down on this, though. I’ve often wondered whether that’s because developers take more care in this area now, knowing that their code will be read and criticized by many other developers, or because one’s personal standards are raised by spending time studying more code by other developers than you might see just working within a single company or team.
In the hands of a skilled set of developers, a shared vision for how the code they’re working on together lets that part of the work become ingrained as a set of habits and permits them to reserve their brainpower for only the tasks that provide value to the project.
Additional Reading & Sources
- The Art & Logic Programming Style Guide: http://styleguide.artandlogic.com/
- Code Complete, Steve McConnell, Microsoft Press 2004
- Literate Programming, Donald Knuth, Center for the Study of Language and Information, 1992
- The Elements of Programming Style, Kernighan and Plauger, McGraw-Hill, 1978
