Development Team/Coding Standards

In This Guide:

1 DareNET Development Wiki - Coding Standards
2 Comments
- 2.1 Multiple Line
- 2.2 Single Line
3 Indentation
4 Separation
5 Braces
6 Variable naming
7 Use of char pointers
8 Linefeeds
9 Portability
10 External Dependencies
11 Profiling and Performance

DareNET Development Wiki - Coding Standards

The following are a set of standards that should be adhered to when writing patches for ircd-darenet and services-darenet. Since these programs are based on the works of others (outside of the DareNET development team), it's reasonable to assume not all code will follow them. This, of course, will be rectified with time.

Comments

Comments can add immensely to the readability of a program, but used heavily or poorly placed they can render good code completely incomprehensible.

That being said, good places to put comments are:

a broad overview at the beginning of a module
data structure definitions
global variable definition
at the beginning of a function
tricky steps within a function

You should also strive to doxify your comments, where suitable.

Multiple Line

Multiple line comments should follow the C-style comment, for example: <source lang="c" line start=1 > /**

* This is a multiple line comment.
* - SecretAgent
*/</source>

Single Line

Single line comments should also be in the C style, for example: <source lang="c" line start=1 > /**< This is a one-line comment. - SecretAgent */</source>

Please avoid using C++-style single line comments (e.g. // Something here).

Additionally, the opening / of all comments should be indented to the same level as the code to which it applies, for example:

<source lang="c" line start=1 >if (fubar()) { /* * Fouled up beyond all recognition. Print a nastygram * and attempt to clean up. If that doesn't work, * die horribly, and try to crash the system while * we're at it. */ ... }</source>

Indentation

Tabs. Tabs. ONLY TABS.

Use a single tab for each level of indentation, for example: <source lang="c" line start=1 > int main() {

 if (condition)
 {
   code
 }

}</source>

Separation

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

NOT

Braces

Always put braces opening and closing blocks on separate lines, see the indentation example.

For example, place braces like this: <source lang="c" line start=1 > if (!(bp = malloc(sizeof (Buffer)))) {

 perror("malloc");
 abort();

} </source>

and NOT: <source lang="c" line start=1 > if (!(bp = malloc(sizeof (Buffer)))) {

 perror("malloc");
 abort();

}</source>

Variable naming

Length is not a virtue in a name; clarity of expression is. A global variable rarely used may deserve a long name, maxphysaddr say. An array index used on every line of a loop needn't be named any more elaborately than i. Saying index or elementnumber is more to type (or calls upon your text editor) and obscures the details of the computation. When the variable names are huge, it's harder to see what's going on.

Struct names should be in camel case with a leading capital letter, for example, "MyBagOfBones". Variable names can be either in camel case with a leading capital letter or alternatively all lower case, so long as the same naming convention is adhered to throughout. Constants and enum values should always be completely in CAPITALS and underscores may be used.

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.

Linefeeds

Unix linefeeds only please. We do not like to see our screens covered in ^M.

Additionally, the maximum line width is 80 characters. If you are writing a longer line, try to break it at a logical point and continue on the next line with the same indenting. Use of backslash is okay; however, multi-line literals might cause less confusion if they are defined before the function start.

Portability

Always make sure your code is portable to all supported operating systems. Don't write code that only works on Linux. Test your code on all platforms or ask for help from other developers who have the platforms you want to test on.

External Dependencies

You must not use any dependencies that are not available as standard on all supported operating systems beyond libc, and whatever else is currently needed to build the ircd/services. If you absolutely must do so, you will need approval from the Development Manager first.

Profiling and Performance

It is one thing to assume that code performs bad, it is another thing to prove that it actually is. A lot of experienced programmers talk about 'premature optimization', and here is what it means: if you have a piece of code called once on start up that takes 10 seconds instead of one second to run, and a piece of code that takes 0.05 seconds to run when it should take 0.01, and it is called once per second, the second piece of code is the priority.

In other words, make sure that what you think is slow, and a performance problem in ircd-*/services-* actually is.

more to come, possibly...