Poorly Formatted Code Costs You Money

After nearly 10 years of working on complex systems I think I have nailed down why poorly formatted code annoys me so much. It wastes time. Complex logic requires whitespace in order for the reader to make sense of it in the same way that punctuation is used in sentences. If the whole thing looks like a dog’s breakfast, it makes it more difficult to understand.

When a person approaches poorly laid out code, they have two choices:

• battle through it
• clean it up and make sense of it

The first one results in an exercise in frustration, the second… well, that’s a beast unto itself.

A long time ago, in my first job, I was working for a consultancy at a major telecoms company on a very large system. The system was used to activate telecoms products on individual lines and talked to telephone exchanges across the network. The project was in its tenth year and had fallen into a steady routine of releases. Regression tests had been written years earlier, but had long since fallen by the wayside. A new project manager came in with an agenda of improvement, and the process to get the tests running again began in earnest.

I was given the task of redeveloping telephone exchange simulators that the tests made use of. These Perl daemon servers would listen on a pipe, take some text in, interpret it and spit out what was expected of an actual telephone exchange of the appropriate manufacturer and version.

I had never worked on anything like this before and asked whether there was any documentation. The response as I remember it was “Bwahahaha! Documentation?”. OK, maybe not quite that dramatic, more along the lines of… “Nothing concrete but it has a lot of comments”.

Understatement of the millennium. Just a sample:

$i++; # add 1 to the value of i

Apparently, the project had taken on a contractor years previously who wasn’t particularly good. Rather than getting rid of him (they didn’t care as they were being paid by the hour for the bum on the seat), they got him to comment the code. Obviously annoyed that he was being sidelined, he commented every single line out of pure spite.

The code wasn’t great to begin with, but in this state it was unreadable! The first thing I did was strip out the redundant comments (some 20,000 lines worth) and checked in a clean copy. The next day one of the senior programmers and the version control manager gave me a a very stern talking to!

It seems that even though no one could argue with my intentions and everyone agreed that it was the right thing to do, it played havoc with the merge tracking. Everything had changed and it would now be impossible to see what my actual code changes were!

The same issue arises with non-standardized code. On a large project there are a lot of people working against the same code base. Some will be good, others not so much. Everyone iterates through each others classes, making changes as is warranted. Now imagine the scenario above, but with numerous people working on various branches of code that all have to be merged back together.

Your programmers now have the same choice:

• do they slowly battle with illegible code in dealing with the task at , or
• do they reformat and take up someone else’s time as they struggle to work out what of the multiple versions needs to go into the final release?

Not a pretty choice. But there is hope!

Actually apply a coding standard.

Give anyone who does not apply it a good talking to. You could establish one using current naming structures, layouts, consensus etc. But you will probably end up making life more difficult for yourself. Getting code formatters to behave just the way you want to and then getting those changes out to everyone on the team takes time, and in a project situation, that’s a rare commodity.

Using Java? Use the Sun standard. ALT-SHIFT-F will automatically format Java code to it by default in Netbeans, and CTRL-SHIFT-F does the same in Eclipse. Weird naming conventions are great for your pet project, but just use the defaults in real life. Personal preference has little relevance in reality. The curly brackets debate happened a long time ago, and no one won. I have used Jalopy in the past as a custom formatter where some weird conventions were dictated. Even though it was supposedly a standard, I realized that few other on the project team did the same, because it took too much time to set up and they didn’t know what the big deal was anyway… *sigh*

Use standard coding conventions. Keep a close eye on anyone who checks in nonsense because poor formatting is often an indicator of poor quality code in other ways, and it will take time to clean up their mess. Time that could be better spent bringing your project in on budget.