Coding Guidelines - Teach, don't Force

written by André Gawron, 02. July 2012

TL;DR: Don't force guidelines onto the programmer's mind, teach and educate them.

Coding guidelines, styleguides, whatever you call them - everybody involved in Programming1 knows the burden of writing code which will be read by somebody else some time in the future. There was this idea of setting up a couple of best-practices regarding the way code should look like. You know, hungarian notation2, no line bigger than 70 characters, no function bigger than 50 lines and brackets in the same line or standalone. These guidelines came and still come in various number of ways.

The purpose of this rule-set had good intentions: make code readable to everybody who followed the guide. The problem, though, is that programmers are very expressive people. They think a lot, sometimes hours before doing any visual work and, at the end of the day, they forge their thoughts into code. The way they're writing it down has to be as natural as it can get, to not lose the process they made while thinking for the solution of the problem. The result is the way programmers express themselves - through code.

Coding guidelines force programmers to think about the visual appearance of their code, losing track of the actual problem. Don't get me wrong, it's important that rules exist, especially for the own programmer's sake3 and there's actually a bad way of expressing one's self, but most of the time those guidelines are broadly defined, cover a lot of small things and get in the way of programmers until they get upset with their work environment. If a company gets lucky the programmers get creative in gaming the system effectively, dodging the coding guidelines all together and get work done again.

Instead of forcing the guidelines onto the programmer, it's better to educate him. Make it clear to him why it's a good approach to fill in a blank line every now and then, why it's better to give variables reasonable names. A programmer adjusts his style of coding several times through his career. He's influenced by other peers, by other code, by his own (life) experience. People change while they grow up and beyond that, so do programmers change the way they think, the way they act, and, in the end, the way they express themselves. Writing readable code is just another item on the programmer's learning schedule - and as everything else, it will take time.

Where to start?

For myself, I think it's very important to have proper indentation4 and a reasonable variable names. Although people fight over the number of tabs or spaces, I believe it's an easy habit to actually learn and change - having a proper editor helps a lot. As an emacs user, I only hit TAB once and it properly indents the code, I don't care if I have to use 2 spaces or 4 tabs (with 3 spaces for each tab), or whatever. TAB and I'm done.

The catch is to settle on one way to indent though. Normally, people say either tabs or spaces but that's not a solution. There are several situations where a mix of them is better. See the following code:

--->hello_world(:first_name,
--->--->--->--->:last_name)

This code is using a tab-size of 4, everything's nicely in line. The good thing about using tabs is that it's easy to change the size without really losing any readability - you prefer a tabsize of two? Good! Four? No Problem! But that's a false friend. If I change the tab size to 85, it will mess up the assignments:

------->hello_world(:first_name,
------->------->------->------->:last_name)

Smarttabs realizes that you actually align :last_name to be in the same column as :first_name so it uses spaces instead of tabs. As the example above, using tabs would cause the :last_name to be way off. It is the same logic when you actually align assigments of variables to be in one column:

var_name........= 'foo'
longer_var_name.= 'bar'

If you would align with tabs instead of spaces, changing the tabsize would result in ugly code:

var_name--->--->= 'foo'
longer_var_name.= 'bar'

var_name------->------->= 'foo'
longer_var_name------->= 'bar'

Even worse:

var_name------->------->= 'foo'
longer_var_name.= 'bar'

The folks using spaces will cheer now "I told you so" but the disadvantage of using spaces is obviously the lack of customizing. Do you like 2 spaces instead of 4 because you think it's more readable? Too bad, we're using 4 here. Change your habit. Every time a programmer get forced to change something without reasonable arguments, it makes him unhappy. We don't want unhappy coders. Unhappy programmers aren't living up their potential.

Incoming: Smarttabs

There's a solution: use tabs for the indentation, spaces for the alignment. What is the alignment I hear you ask, have a look at the following example code:

--->hello_world(:first_name,
--->............:last_name)

Every line of code which you align to the line above (for example, you want the = of variable assignments to be in one line) is affected and might be horrible aligned to each other when switching the tablutor size. Unfortunatly, since most editors don't really support such differentiation in an easy way6, the manual effort you have to put into aligning is not worth the readability it provides. So nothing will change.

Luckily for us emacs7 users out there, Smarttabs exists. It knows when to use tabs and when to insert spaces for the alignment most of the time7 and I never had any regrets nor problems using this module. Although this situation might not occur that often in your codebase, it's one of those little things which can make a change. Give it a try if you haven't known it yet.

  1. and most likely in any area where you can express yourself in different ways
  2. considered bad-practice nowadays
  3. who can read code after months off?
  4. I'd also add line breaks, but that's another topic
  5. whoever like that much indentation
  6. prove me wrong, please
  7. and of course for Vim as well: http://www.vim.org/scripts/script.php?script_id=231
  8. yeah, it does fail occasionally