Rude Code

In this second part of my “Etiquette of Programming” series I’m going to talk about making sure your code fits in with the style of existing code, while helping to bring it up to best practice standards.

When you’re working on an existing codebase, either fixing bugs or enhancing features, you’ll be going into the code and adding more code. When someone has to come back to this section and improve the feature or fix more bugs (not that you would introduce any, would you?) they need to read both the original code and your code. If your code sticks out, or causes the reader to say “Whoa, what’s going on here?” then your code is rude, and no-one likes rude people do they?

Just like writing prose, everyone has a different style of writing coding. People prefer different programming paradigms, design patterns, variable naming schemes and have different aesthetic preferences for spacing their code out with white space. There are more differences, but these four are the main aspects that make up your style of code. I’m going to talk about all four aspects in turn, from rudest to nicest.

Most people code in an object orientated style, but most languages allow you to pick and choose between procedural and functional styles as you wish. Each style has its own benefits and drawbacks, and each should be used in the right place. What you should avoid is switching styles in the same section of code. The mental switch required for someone who is reading code written in multiple styles is too great for it to be an easy or enjoyable experience.

If you choose to write your code in an object orientated style the you could chose to use any number of design patterns. From factories and singletons to full blown class hierarchies design patterns can be incredibly complicated. They all solve essentially the same problem though. They aim to help you structure your code better to give you a more reliable and more maintainable program. An existing code base will usually have evidence of design patterns being in use. Whatever you think of the particular patterns in use, if you want you code to be maintainable then it’s important to use the same patterns.

The final three points are not as important as the first two, but combined they can really cause great difficulty for those reading and extending your code. Most of the time you’ll be using APIs that you don’t know too well. You’ll probably now that there is a function or variable that does what you want, but you’ll need to guess at its name, or look it up. Consistent naming schemes greatly aid in remembering all the nooks and crannies of an API and reduce the mental effort needed to code using it. Typically you’ll be using several different libraries which will have different naming schemes, but if you can be as consistent as possible in the code that you control you’ll have more room in your head for more interesting things.

Lastly we have whitespace. In most languages whitespace is unimportant, and even in languages such as Python where it is, they are pretty forgiving about how you format your code. Four or two space indentation. Braces on the same or next line. Spaces around operators. The variations in style are enormous, but when you’re making a bug fix resist the temptation to change the style to fit your view because it will obscure the change that you’re actually making. If you need to reformat code it should be done in a single, dedicated revision which is clearly marked as only affecting white space.

For code to be maintainable and extendable it ideally looks as is it was written by just one person. None of these points are meant as hard and fast rules. Rather they are something to bear in mind to try and help you rein your natural desire to make a mark on the code. Best practice dogma changes over time and code should evolve with it. However, it should evolve in a dedicated refactoring step not piece by piece as new features are added.

Next time I’ll talk about the etiquette of source control and how it should be used to make your colleagues lives easier.