Coding Conventions

Hey iDevBlogADay,

todays post shifts focus a little bit away from graphics to a more fundamental issue when programming in a team. At Limbic, we’ve recently started a new project, and I love that. Starting with a clean slate, looking back at previous projects, what was good, what was not so good, and trying to do better. This made me reflect a little bit about coding conventions. Let me present you what I’ve come up with.

Coding Conventions

Coding conventions are a very difficult topic. Many religious wars have been fought about this. Everyone that writes code has an opinion on this, and many think their solution is the best. But I think they are completely missing the point. The goal of coding conventions is not to win a beauty contest (which would be very subjective anyways), but to make it easy for others to understand your code, and to add more code that fits in well.

A classical example for coding conventions is the indent styles. A good programmer will have found his specific indent style at which he can work effectively. But a great programmer can work at any given style, and make his code match the surrounding code. As such, it doesn’t really matter what style is chosen. It is more important that everyone sticks to it.

The necessity for a shared coding convention is most obvious when you look at a commit log, and you can see that every single line of a file you’ve edited has been re-indented, brackets moved around, variables and functions renamed by someone else. And when you open it in your editor, half of the text is indented differently than the rest. Because of this you can’t figure out what your own code was originally intended to do, even though you wrote it. There is a good chance you have seen this happening to you. And the other programmer didn’t even mean to offend you, he just wanted to “improve the code” and didn’t know any better.

So far, so good, but which seat should I take style should be used?

Ask 100 programmers, and you’ll get 100 different answers. And each will tell you that his is the one and only style. And that’s the problem: the one and only style simply does not exist, and everyone learned programming in a different way, hence habits differ. Obviously, when you start a new codebase, you want to chose one style, because otherwise everyone will write whatever he or she likes, and it will be chaos.

You’ll probably have that programmer on the team who will be like “oh, it’s easy, just use my style!”. The problem with that usually is that he never documented that style, and he would probably describe a lot of rules with words like “obviously” and “trivial”, instead of properly defining them.

And that’s why I think the best solution to this is to just go out and pick one of the existing popular coding conventions, and stick to it precisely. At Limbic, we decided to use the Google C++ Style Guide (it comes with cpplint, a great script to check for a number of convention violations). Even though a lot of aspects were unintuitive to me at first, I accepted this style and worked with it. And now I love it, it definitely helped me become a better programmer. And I also learned this and that about C++.

Using a popular convention helps when bringing in new coders, too. It’s easier to tell a new programmer “check out the Google Conventions” than to tell him “just look at the rest of the code and do it the same way”, especially if they are somewhat esoteric (I’m pretty sure everyone has seen his share of esoteric code). In case of doubt about a certain style, there is always a place to go back to and look up how it was meant to be (and why).

Finally, keep in mind that the conventions are obviously not set in stone. If a programmer feels that a certain rule is odd, I’d suggest to go and try it anyways. Usually, it’s not as bad as it may sound initially. And more often than not, it has some great advantages that you didn’t think of initially. If that doesn’t work, you can still change the rules, by writing up some extensions.

Why are you telling me all this?

That’s a fair question. And I guess the point to take way is as simple as this: I learned that using tolerance when it comes to coding conventions is a huge gain, and fighting for your own style is a huge pain. The art in programming (in a team) is not to write fancy code, but rather to build solid code that is easy to maintain and extend. And that’s a lot easier if everyone pulls in the same direction.

Leave a Reply

Your email address will not be published. Required fields are marked *