mod_musicindex  1.4.1
Developers Notes
 Developers want to keep in mind we are aiming at the cleanest code possible.
 No matter how wicked what the code does is, said code should do dirty
 things with grace and proper documentation ;)

 The coding style used throughout the code tries to stick as much as
 possible to the Linux Kernel Coding Style.

 Developers should also take special care to typing. Strict typing is the
 first protection against coding mistakes that might lead to dreadful
 crashes. The same applies to function modifier (in particular the
 @c static modifier, that should be used whenever appropriate).

 Finally, we try to put Apache's specific arguments to functions at the
 beginning of their param list.

Coding style reminders

Rules about pointers

These are often forgotten, so let's recap how to enforce typing on pointers:

  • const char *answer_ptr = "Forty-Two";
    • answer_ptr = "Fifty-One"; is legal (answer_ptr is a variable)
    • *answer_ptr = 'X'; is illegal (*answer_ptr is a constant)
  • char *const name_ptr = "Test";
    • name_ptr = "New"; is illegal (name_ptr is constant)
    • *name_ptr = 'B'; is legal (*name_ptr is a char)
  • const char *const title_ptr = "Title";
    • title_ptr = "New"; is illegal (title_ptr is constant)
    • *title_ptr = 'X'; is illegal (*title_ptr is a constant)

Enforcing these simple rules helps code readability (as well as improving build time checks): in fact, defining a pointer like const char *p; tells us that this pointer will only be used to navigate in a string, but won't be used to modify it.

Rules about variables

  • As a rule of thumb, always try to declare all function variables at the beginning of the function, and avoid as much as possible to declare subvariables in blocks.
  • In any case, never declare new variables after code in a block.
  • Finally, special care should be borne to storage space: always declare as little as possible: we want the module to consume as few memory as possible. That also applies to functions return types.

The restrict contract

I, [insert your name], a PROFESSIONAL or AMATEUR [circle one] programmer recognize that there are limits to what a compiler can do. I certify that, to the best of my knowledge, there are no magic elves or monkeys in the compiler which through the forces of fairy dust can always make code faster. I understand that there are some problems for which there is not enough information to solve. I hereby declare that given the opportunity to provide the compiler with sufficient information, perhaps through some key word, I will gladly use said keyword and not bitch and moan about how "the compiler should be doing this for me."

In this case, I promise that the pointer declared along with the restrict qualifier is not aliased. I certify that writes through this pointer will not effect the values read through any other pointer available in the same context which is also declared as restricted.

Your agreement to this contract is implied by use of the restrict keyword ;)