I’m an old school C programmers guy and I stay true to some of the older and commonly used rules present in many open source and similar projects. Since I sometimes rant about this to people, I thought I’d amuse my surrounding by stating them here for public use/ridicule. Of course heavily inspired by the great and superior The Ten Commandments for C Programmers. My commandments are not necessarily in any prio order.
Thy Code Shall Be Narrow
Only in very rare situations should code be allowed to be wider than 80 columns. I want my two or three windows next to each other horizontally and still see the code fine. Not to mention the occasional loading up in an editor in a 80 columns terminal and that is should be possibly print nicely (for reviews etc). Wide code is also harder to read I think, quite similarly to how very wide texts in web pages etc aren’t kind to your eyes either.
Thou Shall Not Use Long Symbol Names
To be able to keep the code easily readable by human eyes so that you quickly get an overview and understand things, you simply need to keep the function and variable names fairly short. Not to mention that the code gets harder to keep within 80 columns if you use ridiculously long names.
Comments Shall Be Plenty
Yes, this is something we know everyone says and few live up to. In statistical analyzes of my own C code I usually reach around 25-27% comments and I’m usually happy with that amount. Comments should explain what is otherwise not obvious in the code.
No Hiding What’s Really Happening
I’m not a fan of overloaded operators or snazzy macros that do fancy stuff without it being noticeable in the code. It should be clear when reading the code what it does. That’s also one of the reasons you don’t catch me doing a lot of C++ work…
Thou Shalt Hunt Down and Kill Compiler Warnings
Compiler warnings may be significant and in some cases they are not. Either way, it is our duty to silence them at all times. Firstly because it is often simpler to fix the code to not warn than to figure out if the warning is indeed right or not, but perhaps primarily because it makes it harder to see new warnings appearing if the old ones have been left there.
Write Portable Code Unless Forced by Evil
You may first believe that your code will live on forever on this single platform with this single compiler, but soon and very soon you will learn otherwise. Then you will cheer this rule as it makes you consider unaligned memory accesses, assuming byte-order of binary data or the size of your ‘long’ variable type.
Repeat Not, Use Functions
I see a lot of “copy and paste” programming in my daily life and I’ve learned that sooner or later such practices lead to sorrow. If you paste the same code on multiple places it not only makes it repetitive and boring to update it when an API or something changes, more seriously it increases the risk that you address bugs only on one out of many places or that the fix differ etc. It also makes the code larger and thus harder to follow and understand.
Thou Shalt Not Typedef Away Pointers
A really nasty habit to be seen in some source codes is when people use typedefs to define their own types that is simply a pointer to something. Like with ‘typedef struct whatever * whatever_t’. While I’m in general against excessive typedefing, I’m fine with them in many cases but not when used to hide pointers to look like “ordinary” types. It makes code harder to follow.
Defines, no fixed numbers
Code that relies on zero and non-zero can get away without this, but as soon as you start relying on more numbers in the code you must start using #defines or possibly enums to make them appear with names in the code. Using names is more clever than hardcoded numbers since you can avoid having to explain the number in a comment, and of course it’ll be easier to change the actual number in the code at a later point without it being a painful search-and-replace operation.
