Difference between revisions of "CodingConventions"

Coding Conventions

This page lists the coding conventions actually in use within Glob2. The intended purpose is to have coherent-looking code through the project. Sorry if this different to your usual conventions.

KISS: Keep it Simple Stupid

All new code written in Glob2 should be obvious. Don't use clever tricks. Everything should be kept as simple as possible, but no simpler. This is a fundamental principle, and all new code should be kept with KISS in mind.

Maintainability Is God

If code is readable, if its maintainable, then it is good. Sometimes people get haggled about using pure OO or get/set. Make sure that your code is maintainable. If you change one portion, always try to minimize the amount of other code segments that need updated. This encompasses many techniques. Encapsulation is one of the best.

Indentation

Code should be indented by tabs. A tab should be equivalent to 4 spaces. Please note that in the code below, non-breaking spaces are used because tabs don't display correctly in web pages.

Class and struct naming

Classes should begin with capitals, new words should be denoted by a capital, and words should not be separated by underscores or dashes. In other words,

class TotoIsMyFriend { }; // correct

instead of:

class toto_is_my_friend{}; // wrong

Class members, variables, and C function follow the same convention but without the initial capital:

void totoIsMyFriend(void); // correct

instead of:

void Toto-is-my-friend(void); // wrong

Bracket placement

Brackets {} should be placed alone on a line, except if there is no or only one function call within them.

class Toto
{
    int i;
    void totoIsMyFriend(void) { return i; };
}; // correct

instead of:

class Toto {
    int i;
    void Toto-is-my-friend(void) {
        return i;
    };
}; // wrong

Emacs

If you use Emacs as your editor, you can make it apply these rules to Globulation 2 files by putting the following in the .emacs file in your home directory:

(defconst glob2-c-style
 '((c-basic-offset	. 4)
   (c-offsets-alist            . ((substatement-open . 0)
				   (inline-open	. 0)
				   ))
   )
 "Globulation 2 programming style")

;; Customizations for all modes in CC Mode.
(defun glob2-c-mode-common-hook ()
 (c-add-style "glob2" glob2-c-style)
 )

(add-hook 'c-mode-common-hook 'glob2-c-mode-common-hook)

And adding the following to the top line of each of your source files:

/* emacs settings information: -*- mode: c++; tab-width: 4; c-file-style: "glob2"; -*- */

Proposed Conventions

This section discusses proposals for programming style rules that have not yet been widely accepted

Counting

When referring to the total number of items of a particular type that there are, the current rule is to use numberOfFoo. I find this confusing, as I expect numberOfFoo to refer to the index number of a particular instance of foo. Some alternatives include:

• fooCount
• fooTotal
• fooSize

fooCount seems the easiest to read of the three, fooTotal also makes sense, and fooSize, while confusing, mirrors the foo.size() convention used in STL containers.

By extension, where there is an ordered list of things (most likely an enum), we should always have the following definitions:

enum foo { foo1, foo2, ... fooN };
static const int fooMin = foo1;
static const int fooMax = fooN;
static const int fooCount = fooMax - fooMin + 1;

Getting and setting

At present, it's standard to get values with getFoo() and set them with setFoo(value). While this is clear, it doesn't fit with the C++ convention of using foo() and foo(value). It also doesn't distinguish between the cases where we are supposed to think of getFoo() and setFoo() as simple wrappers around private variables vs. where we should expect more significant processing to be done. I propose that we use getFoo() only where the user should expect significant processing to be done. For example, GAGCore::getFilename() searches an entire list of directories for a file, whereas debugLevel() just sets an internal variable.

documentation

When doing documentation, a comment section for a function should look something like this:

/**
 * Any comments go here
 * @param string $foo 
 * @param int $bar
 * @return boolean
 * @access private
 * @todo document
 */

keep in mind not all of these items are always needed. if it doesn't take any parameters, that section is not needed.
so if it doesn't take any parameters, you can leave @param out