Home Download News FAQ / Knowledge Base Screenshots Documentation Support Site map
philosophical imaginary

Differences

This shows you the differences between two versions of the page.

documentation:coding_style [2013/09/25 14:57] (current)
ajc
Line 1: Line 1:
 +====== 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. As far as I'm concerned, they're designed to promote Emacs - and since vi is the One True Editor, there's no need for that. (No, you're not required to use vi as your text editor. Go ahead and use whatever you're comfortable with.)
 +
 +We indent using tabs, and tabs by default are 8 characters. Let's keep it that way. When you need to begin a new block of control, go in by one tab. Please make sure it's a real tab rather than 8 spaces, and don't be surprised if someone goes through your source code replacing any series of 8 spaces with a tab.
 +
 +The acceptable line width is up to 132 columns.  For a long time, we tried to keep everything constrained to an 80 column screen width, but we ended up having a lot of lines bunched up on the right side of the screen. Some might argue that this means we're doing too much in each function, but in general we try to code everything in the most understandable way possible.
 +
 +Quite simply, we do braces the Kerninghan and Ritchie way:
 +
 +<code>
 +
 +if (condition is true) {
 + do something;
 +
 +
 +</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:
 +
 +<code>
 +
 +do {
 + do something;
 +} while (condition is true); 
 +
 +</code>
 +
 +When there are multiple 'else' conditions to an if-statement, we try to keep each block separate, like this:
 +
 +<code>
 +
 +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;
 +
 +
 +</code>
 +
 +We think this makes the code more readable.
 +
 +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 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' followed by one or more 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, and for this we apologize and hope to modify it 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 WebCit program, your code must be threadsafe. Failure to write threadsafe code will result in the infamous 'BOOM!' situation at random and unexpected times.
 +
 +We comment our code voluminously in the Citadel system. Explain what each function does, and if it isn't obvious, explain how it works. Our preferred comment style is like this:
 +
 +<code>
 +
 +  /*
 +   * This is a comment. We love comments.
 +   * If there are second and/or subsequent lines, do it like this.
 +   */ 
 +
 +</code>
 +
 +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.
  
Copyright © 1987-2014 Uncensored Communications Group. All rights reserved.     Login (site admin)