A programmer’s paranoia

Every single day of my life I watch and use other people code/libraries/programs/framework done in C/C++ ad other languages. I hate a lot of things and this is my personal list of things that make me mad.

#10 – Stupid comments

Comments are a very important. A well written comment says more than a Doxygen gargantuan generated document. But a lot of people haven’t understood that a comment is used to comment an important passage or implementation.

// out of the loop
break;
// here I auto-increment the base
base++;
// 256 should be enough
char buffer[256]

are stupid comments.

#9 – Line ending mixture and cleanness

You want to use \r\n as line terminator? Ok. You want to use the standard UNIX \n? Ok. You are an old Macintosh fan and you see only \r around there? Ok. But please be coherent in all your files: not not mix different line ending, different indentation characters, do not leave trailing white-spaces and the most important: do not mix different coding style on the same file please.

#8 – Tab for indentation

Not every editor in the world uses a 4 spaces tab. Emacs, vi and a lot of shells around there use a 8 spaces tab and this is the rule. If you use a 4 spaces tab please specify it.

#7 – Foreign languages

I’m italian. Ok. But a open source program that want to be used all around the world must contains in its code only english comments and english mnemonic variable. Period. A mixture of two different languages is even worst. So please no more pippo, topolino, toto and tata.

#6 – If it works for me it will works for you

Do not assume that your C, C++ code work in a cross-compile, cross-platform reality. There are a lot of bogus compiler around there and it’s plain easy to see subtle errors spawning on other compilers. Specify in the documentation where your code as been tested.

#5 – Compilers’ extensions

Do not write code that is full of compiler specific extensions to the standard C/C++. Strange #pragmas, new keywords or // comments in C code. If you want to write portable programs so do follow the standard for C and C++. Or says: “my work functions only on Visual Studio .NET 2008 that is just one of the ~200 C++ compilers out there”.

#4 – Stupid macros

Macros must be in this fashion: UNIQUEPREFIX_THE_NAME_OF_THE_MACROS. Macros like min, PI, forall, LOG, GetMessage are stupid, dangerous and useless. If you don’t believe me read the boost documentation regarding the macro BOOST_PREVENT_MACRO_SUBSTITUTION.

#3 – Global namespace pollution

Never have global variable. Never export functions that are not prefixed with an ID or not included in a namespace or have a too general name. Exporting the function format or the variable gState will pollute the global namespace of the user.

#2 – Undocumented interfaces

Please ship your code with at last some basic documentation and increasing difficulty examples. You can’t expect that the user must read the entire documentation only to understand the right order of functions call or classes instantiation. Remember: 3/4 examples say more than the entire documentation. The user will start immediately using your code and then it will add more advanced features as his understanding of your code increase. README file, man files, html pages, pdf or very descriptive comments are welcome.

#1 – No license

Every file you create must have a companion license or at least a copyright notice or a declaration of public domain. People need to know if they can include your code in their applications. Nobody cannot assume what kind of restriction they must follow. It happens some years ago that a dude pointed me that I used his code but I do not report the BSD license text in the documentation of the binary release. A license-less file isn’t automagically a licensed one.