How to write good code

Posted: June 2, 2008 in Best Practice
Tags:

Having been coding as a programmer, we have seen and write a lot of bad code. Code is not good just because it works. So here’s a quick list of that we would better keep in mind while coding.

1. Don’t sacrifice code maintainability to performance, unless it’s strictly necessary.

This happens very often. You have to consider that your code is likely to be read by many persons, and some of them will read it after you might have parted from that company. Remember that you won’t remember what your own code does after few weeks. So always try to put things in the most readable and obvious form, even if this will require writing more lines of code, or having less performing code. Of course this is not so important if performance is your number one issue. Try, for instance, to avoid use of the ?: operator everybody will understand it anyway, but a good old if statement will do it, so why not going for it?

2. Be precise as a Swiss clock, when it comes to naming conventions.

Nobody wants to read class names or variable names that look like gibberish. Don’t be mean on the keyboard: when we type, remember that somebody else will have to read it, so be extensive.

  1. Name our variable NumberOfItems rather than items_n. Don’t use cryptic prefixes to class name. Name our class ClientMessageOperationsBasicFunctor rather than CMOpFunctor. It’s a lot more typing for us, but a lot less hassle reading for the ones that will come after us.

  2. Don’t change your conventions. If we are calling the iterators i, don’t call any of them n, ever. You will induce confusion to your reader. It doesn’t seem as important as it actually is. If you call a class ClientMessageBlockContact, then do not have ServerMessageContactBlock. Be perfect, be precise, be obsessed.

3. Use a good and consistent indentation style.

Never ever have more than one blank line. Don’t have trailing spaces at the end of the lines. Don’t have blank spaces or TAB characters in blank lines. A blank line must be blank, that is.Be consistent: don’t use TABs to indent in one file, and spaces in another one. Possibly, use 8-chars wide TABs to indent. If you find yourself going beyond 80 rows too often, then that could be an indication that there might be some design flaws in your program. Tweak your editor to show you the end-of-line character and the TABs.

4. Use TODOs and FIXMEs.

If you know that you, or somebody else, will have to return on a certain piece of code to add or modify some functionality, please mark it with a TODO. If you know that a piece of code is buggy but you can’t fix it right now, add a FIXME marker. Later on, it will be easy to grep the source tree for TODOs and FIXMEs and analyze them, especially if they’re very well commented.

5. Comment your own code.

Seriously: you’re going to forget, sooner than you think. Just invest 5% of your time in writing commented code. Never assume that code is self-explanatory, just write a couple of lines for everything you do. Comments are not only meant to generate doxygen documentation. You have to assume that somebody else will read your code and need to modify/extend it.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s