Difference between revisions of "Coding Guidelines"

From the makers of InspIRCd.
Jump to: navigation, search
(Templates)
Line 100: Line 100:
 
</pre>
 
</pre>
 
Plus, placing the name at the bottom of the declaration makes readability more difficult (as you have to scroll down to the bottom of the struct to find its name).
 
Plus, placing the name at the bottom of the declaration makes readability more difficult (as you have to scroll down to the bottom of the struct to find its name).
 +
 +
==== Variable naming ====
 +
Class and struct names should be in camel case '''with a leading capital letter''', for example "MyBagOfBones" and not "my_bag_of_bones" or "mybagofbones". Variable names can be in either camel case with a leading capital letter or alternatively all lower case, so long as the same naming convention is adhered to througout the class.
 +
No classes or variables should be named in capitals unless this makes sense for the name (for example "class ''DNS''").
 +
Constants and enum values should always be completely in CAPITALS and underscores ''may'' be used, for example:
 +
<pre>
 +
enum DecayState
 +
{
 +
        DECAYED_MOULDY  = 0,
 +
        DECAYED_SMELLY  = 1,
 +
        DECAYED_MAGGOTS = 2
 +
};
 +
</pre>
 +
All value names in an enum should be started with the same text which should be related in some way to the enum's use. For example "DNS_CNAME, DNS_A, DNS_AAAA".
 +
 +
==== Use of references ====
 +
Wherever possible, when dealing with any class larger than the 4 bytes in size, pass a const reference rather than a copy of the class.
 +
For example:
 +
<pre>
 +
MyThingy::MyThingy(const std::string &thingyvalue)
 +
{
 +
}
 +
</pre>
 +
Of course, if you intended to change the string you can just omit the 'const'.
 +
 +
==== Use of char pointers ====
 +
Whenever you use char pointers (char*, char**) try to use const equivalents. This is much safer and avoids ugly and dangerous casts. For example:
 +
<pre>
 +
MyThingy::Thingify(const char** wotsits)
 +
{
 +
}
 +
</pre>
 +
If it is possible without performance loss, consider avoiding char pointers altogether and using std::string or irc::string instead.

Revision as of 18:01, 30 November 2006

InspIRCd Coding Guidelines

The following are a set of guidelines for writing patches to InspIRCd, or for creating modules for distribution with the official package. These guidelines were written a time after InspIRCd development started, and so not all code yet follows these. This will be rectified with time.

Comments

Multi Line

Multiple line comments should follow the C-style comment, for example:

/*
 * This is a multiple line comment, huzzah..
 */

Single Line

Single line comments should also be in the C style, for example:

/* This is a boring one-line comment */

Doxygen commenting

If you wish your comment to show in doxygen, the comment should be directly above the item you are documenting (a class, function, enum, etc) and the first line should be "/**". For example:

/** This is a doxygen multiline comment.
 * Description of thingymebob here.
 */

The first line after the "**" is used as the short description of the item (up to the full stop) and everything afterwards as the detailed description.

Indentation

Tabs. Tabs. ONLY TABS. Use a single tab for each level of indentation, for example:

int main()
{
<tab>if (condition)
<tab>{
<tab><tab>code
<tab>}
}

Separation

Always put a space in between a keyword like if/while and the condition, for example:

if (foo == bar)

NOT

if(foo == bar)

Braces

Always put braces opening and closing blocks on separate lines, see the identation example. For example, place braces like this:

if (apples == "green")
{
        cout << "Apples are green" << endl;
}

and not:

if (apples == "green") {
        cout << "Apples are green" << endl;
}

The one exception to this is if you are declaring a class method which is only one line long, in that case the following is acceptable in most cases:

class foo : public bar
{
        foo() { }
        getrandomfoo() { return rand(); }
};

Templates

Where possible, use templates rather than #defines. Avoid use of RTTI.

Structs

Structs should be declared in the following fashion:

struct BodyPartBasket
{
        int arms;
        int legs;
        int scrotal_sacs;
};

and not like this:

typedef struct
{
        int arms;
        int legs;
        int scrotal_sacs;
} BodyPartBasket;

The second way is not required in C++ to be able to do this:

BodyPartBasket mybasket;

Plus, placing the name at the bottom of the declaration makes readability more difficult (as you have to scroll down to the bottom of the struct to find its name).

Variable naming

Class and struct names should be in camel case with a leading capital letter, for example "MyBagOfBones" and not "my_bag_of_bones" or "mybagofbones". Variable names can be in either camel case with a leading capital letter or alternatively all lower case, so long as the same naming convention is adhered to througout the class. No classes or variables should be named in capitals unless this makes sense for the name (for example "class DNS"). Constants and enum values should always be completely in CAPITALS and underscores may be used, for example:

enum DecayState
{
        DECAYED_MOULDY  = 0,
        DECAYED_SMELLY  = 1,
        DECAYED_MAGGOTS = 2
};

All value names in an enum should be started with the same text which should be related in some way to the enum's use. For example "DNS_CNAME, DNS_A, DNS_AAAA".

Use of references

Wherever possible, when dealing with any class larger than the 4 bytes in size, pass a const reference rather than a copy of the class. For example:

MyThingy::MyThingy(const std::string &thingyvalue)
{
}

Of course, if you intended to change the string you can just omit the 'const'.

Use of char pointers

Whenever you use char pointers (char*, char**) try to use const equivalents. This is much safer and avoids ugly and dangerous casts. For example:

MyThingy::Thingify(const char** wotsits)
{
}

If it is possible without performance loss, consider avoiding char pointers altogether and using std::string or irc::string instead.