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.

===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 { }; <span style="color: green">// correct</span>

instead of:

class toto_is_my_friend{}; <span style="color: red">// wrong</span>

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

void totoIsMyFriend(void); <span style="color: green">// correct</span>

instead of:

void Toto-is-my-friend(void); <span style="color: red">// wrong</span>

===Bracket placement===

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

class Toto

{

&#160;&#160;&#160;&#160;int i;

&#160;&#160;&#160;&#160;void totoIsMyFriend(void) { return i; };

}; <span style="color: green">// correct</span>

instead of:

class Toto {

&#160;&#160;&#160;&#160;int i;

&#160;&#160;&#160;&#160;void Toto-is-my-friend(void) {

&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;return i;

&#160;&#160;&#160;&#160;};

}; <span style="color: red">// wrong</span>

===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 <code>numberOfFoo</code>. I find this confusing, as I expect <code>numberOfFoo</code> to refer to the index number of a particular instance of foo. Some alternatives include:

* <code>fooCount</code>

* <code>fooTotal</code>

* <code>fooSize</code>

<code>fooCount</code> seems the easiest to read of the three, <code>fooTotal</code> also makes sense, and <code>fooSize</code>, while confusing, mirrors the <code>foo.size()</code> 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 foo_min = foo1;

static const int foo_max = fooN;

static const int foo_count = foo_max - foo_min + 1;

===Getting and setting===

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

[[Category:Developer Resources]]