Salvatore Iovene

Hav­ing been cod­ing for 16 years now (I started quite young), I have seen a lot of bad code. Code is not good just because it works. So here’s a quick list of 10 advice that you’d bet­ter keep in mind while coding.

1. Don’t sac­ri­fice code main­tain­abil­ity to per­for­mance, unless it’s strictly nec­es­sary.

   This hap­pens very often. You have to con­sider that your code is likely to be read by many per­sons, and some of them will read it after you might have parted from that com­pany. Remem­ber that you won’t remem­ber what your own code does after few weeks. So always try to put things in the most read­able and obvi­ous form, even if this will require writ­ing more lines of code, or hav­ing less per­form­ing code. Of course this is not so impor­tant if per­for­mance is your num­ber one issue. Try, for instance, to avoid use of the ?: oper­a­tor in C/C++. Every­body will under­stand it any­way, but a good old if state­ment will do it, so why not going for it?

2. Be pre­cise as a Swiss clock, when it comes to nam­ing con­ven­tions.

   Nobody wants to read class names or vari­able names that look like gib­ber­ish. Don’t be mean on the key­board: when you type, remem­ber that some­body else will have to read it, so be extensive.

   1. Name your vari­able NumberOfItems rather than items_n. Don’t use cryp­tic pre­fixes to class name. Name your class ClientMessageOperationsBasicFunctor rather than CMOpFunctor. It’s a lot more typ­ing for you, but a lot less has­sle read­ing for the ones that will come after you.

   2. Don’t change your con­ven­tions. If you’re call­ing the iter­a­tors i, don’t call any of them n, ever. You will induce con­fu­sion to your reader. It doesn’t seem as impor­tant as it actu­ally is. If you call a class ClientMessageBlockContact, then do not have ServerMessageContactBlock. Be per­fect, be pre­cise, be obsessed.

3. Use a good and con­sis­tent inden­ta­tion style.

   Never ever have more than one blank line. Don’t have trail­ing spaces at the end of the lines. Don’t have blank spaces or TAB char­ac­ters in blank lines. A blank line must be blank, that is.Be con­sis­tent: don’t use TABs to indent in one file, and spaces in another one. Pos­si­bly, use 8-chars wide TABs to indent. If you find your­self going beyond 80 rows too often, then that could be an indi­ca­tion that there might be some design flaws in your pro­gram. Tweak your edi­tor to show you the end-of-line char­ac­ter and the TABs.

4. One class, one file.

   Don’t write files like ServerMessages.h where you write all the class that are ServerMessages. One class goes in one file. If you find your­self think­ing that you can’t do it, review your design.

5. In C/C++, project includes use “”, depen­dency includes use <>.

   If you’re includ­ing a file that’s local to your project, use #include "file.h"; if it’s an exter­nal depen­dency, do #include <file.h>. Why? I’ve seen peo­ple includ­ing <file.h> and then just put things like /usr/includes/my_project in the inclu­sions search path, so that nobody will be able to com­pile before installing. That’s a bad assump­tion. And you don’t want to end up in that error.

6. Always com­pile with -ansi -pedantic -Wall -Werror flags (or sim­i­lar, accord­ing to your com­piler).

   Let’s adhere to stan­dards. Let’s avoid warn­ings. A warn­ing might become an error in the future.

7. Use TODOs and FIXMEs.

   If you know that you, or some­body else, will have to return on a cer­tain piece of code to add or mod­ify some func­tion­al­ity, 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 ana­lyze them, espe­cially if they’re very well commented.

8. Com­ment your own code.

   Seri­ously: you’re going to for­get, sooner than you think. Just invest 5% of your time in writ­ing com­mented code. Never assume that code is self-explanatory, just write a cou­ple of lines for every­thing you do. Com­ments are not only meant to gen­er­ate doxy­gen doc­u­men­ta­tion. You have to assume that some­body else will read your code and need to modify/extend it.

9. Use a ver­sion­ing sys­tem even if you’re work­ing alone.

   Yes, ver­sion­ing is not just for work­ing in a team. Use Darcs or SVN even if you’re work­ing alone: you won’t regret it.Commit often and try to be pro­fes­sional all the time. Later on some­body else might join you. Or then you might find use­ful to revert to pre­vi­ous ver­sions of your pro­gram. And it will help you to keep trace of what you’re doing.

10. Use a bug track­ing sys­tem even if you’re work­ing alone.

    Things like Bugzilla are EXTREMELY use­ful. Usu­ally you will for­get bout a bug after less than 2 days. Every­time you find a bug, either fix it imme­di­ately, or mark it to your per­sonal bugzilla. And always fix bugs first, and then write new code.

Com­mon errors:

• It com­piles, so it works.
• It works here, so it works everywhere.
• Com­ment­ing? We don’t have time to waste, we gotta ship!
• UML dia­grams are useless.
• Plan code so that we can reuse it is use­less: we’ll end up writ­ing every­thing from scratch anyway.
• Unit tests are a waste of time.
• …