The Importance of Following Code Conventions

I’ve found one of the trickiest issues in working with other people’s code is trying to decipher the way they do things programmatically. You can learn an awful lot about how a programmer thinks by reading their code. All too often, the first thing I learn is that they’re wildly disorganized.

Freelancers are frequently self-taught and lack the experience of working in an environment with a lot of other programmers. As a result, they only ever program for themself – not for the poor schlep (me) who has to come along later and try to figure out just what the heck they were trying to do. There’s a distinct lack of useful comments, consistent code structure or well-named functions and variables.

When you work in an environment with a group of programmers, the project lead should define the code conventions that all the programmers need to follow, enforcing them during regular code reviews. This creates a discipline a lot of solo coders lack.

I’ve been lucky to work within groups of programmers, so I know how valuable setting such code conventions can be. When I went out to find freelancers to help us at TechKnowMe, the very first thing I did was set up a code conventions document I expected everyone to follow. It’s very short and very simple. You can download it as a PDF here:

The TechKnowMe Coding Conventions Document

In it, I define my general programming philosophy so that those working with me understand where I’m coming from and what I expect. I then go into the details of how functions and variables should be named and even where brackets should appear. Much of what is in this doc should not be uncommon to most professional programmers, but if you’re a freelancer working alone, I’d strongly recommend adopting either the policies laid out here or setting some of your own.

Of course, creating code conventions is the easy part. Developing the discipline to actually stick to them is the real tricky bit. It’s this discipline, however, that separates the amateur hobbyist from the professional developer.

Leave a Reply




You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>