Coding Style

This is a short document describing the preferred coding style for the Citadel system. These rules are not set in stone, but it's nice to have some measure of consistency, so if you're going to contribute code to any portion of the Citadel system, please at least consider following these conventions.

To begin with, go ahead and completely disregard the GNU coding standards. Code written to those standards is almost as sloppy looking as Richard Stallman himself. We prefer code written to the K&R style, specifically the "Stroustrup" variant.

Indentation and screen width

We indent using tabs, not spaces. And our tab stops are set at 8 characters, as God intended. This is not up for debate. You will be destroyed in a flame war if you use spaces.

The acceptable line width is up to 132 columns. No one is stuck on an 80-column terminal anymore. This is, in fact, why you might find older sections of the Citadel system (particularly the text client) violating our own style guide -- we started the project on true green screen terminals and had an older coding style that looked better on the 80x25 terminals of the era. When we come across this old style, we fix it.

Braces

We place braces on the same line as the control statement that defines the braced code:

if (condition is true) {
	do something;
}

This is also true for function declarations:

int main(int argc, char **argv) {
	some code;
}

The closing brace should be on a line of its own, unless there is a continuation of the same statement such as a while in a do-statement, like this:

do {
	do something;
} while (condition is true);

When there are multiple else conditions to an if statement, keep each block separate, and avoid the "cuddled" else:

if (condition is true) {
	do something;
}

else if (other condition is true) {
	do something;
}

else if (another condition is true) {
	do something;
}

else {
	do something;
}

Please use braces even when a conditional block only contains one statement:

if (condition == true) {
	printf("Condition is true\n");
}

If there are a lot of conditions being checked, it is acceptable to skip the braces if the statement after the if is on the same line, for example:

if (foo != NULL) free(foo);
if (bar != NULL) free(bar);

But never:

if (foo != NULL)
	free(foo);
if (bar != NULL)
	free(bar);

Variable naming conventions

We use two different naming conventions for two different types of code. When you are writing code that is not designed to be utilized by other code, your functions and variable names should be in "Snake Case" -- all lower case with words separated by underscores, such as:

master_startup()
pidfile_fp

The special case is for functions which are intended to be part of the 'server side API' which have names beginning with Ctdl and are in "Camel Case" -- multiple words whose first letter is capitalized, and no underscores, such as:

CtdlAccessCheck()
CtdlGetRelationship()
CtdlEncodeBase64()

We do realize that the existing code does not adhere strictly to this convention, because it was not always done that way from the beginning. It will improve as time goes on.

Functions should be understandable and do one thing, just like in any other code. If you are writing code for the Citadel server or the C side of WebCit, your code must be threadsafe. Failure to write threadsafe code will result in server crashes that suddenly disconnect all users. And no one wants that.

Comments

We comment our code voluminously in the Citadel system. Explain what each function does, and if it isn't obvious, explain how it works. We are currently moving everything over to C99 comment style:

// This is a comment. We love comments.
// If there are second and/or subsequent lines, do it like this.

A little help from the system utilities

When in doubt, you can use the 'indent' utility. It's easy:

indent -kr -i8 filename.c

That'll take care of most of our coding conventions. But remember, 'indent' is not a fix for bad programming.