Coding Style

Before we start writing code, let us discuss a few issues that relate to the Coding Style. Since this is an Open Source project, not only can we expect this code to be read by others, we want it to be read by others. While in general, one should always write code as clean as humanly possible, we all know that people in general tend to take more precaution if they are aware that somebody else might see it. So, again, remember, your the code is intended for everybody to see and enhance.

To make it possible for others to understand the follow your code, a few common techniques should be obeyed by. The placement of braces, while often discussed and as lively a debate as the old ``Vi-vs-Emacs'' issue, is clearly nothing more than a matter of personal opinion. Therefore it does not make a difference if you write

if (x is true) {
we do y
} else {
we do z
}

or

if (x is true) 
{
we do y
} 
else 
{
we do z
}

However, if you were to join an existing Open Source project, please adhere to the style used. Aside from that, there are some other issues that need to be paid attention to. An excellent summary of the most important issues are found in the Linux kernel documentation[25]. Please make sure to read and understand the document - while it is written with the Linux kernel code (C Code) in mind, it is applicable to other languages as well.

One thing that is not mentioned in this document but that is worth pointing out is the use of "$keyword: text $" strings for version control. There exists this nifty little tool ident, which can extract these from the input files, even if they are compiled binaries. While this originates from the RCS Revision Control System, it is very useful just by itself.

I have made a habit of including at least the following two strings in any file of a project:

$Author: Firstname Lastname <email@address> $
$Id: filename, v Version, YYYY/MM/DD HH:MM:SS who Exp $

By including these rather self-explanatory lines in each file of your code, it will later on be as easy as using ident file to determine the version of each file. While this may not necessarily strike you as the best thing since sliced bread for text-files (ie the source), it comes in handy when you want to check a binary. Refer to ident(1) for details.