wiki:DevelopmentGuidelines

Version 1 (modified by tim, 7 years ago) (diff)

--

Development Guidelines

Whilst these guidelines are not compulsory for PC-BSD development, following them will help other developers get their head around your work, and help you to get your head around theirs.

Coding Style

Naming Conventions

All names should reflect in some way, what it is they are labelling. A method which gets user details for example, might be called getUserDetails(). However, different capitalisation rules apply.

  • Class names should be in CamelCase with the initial character capitalised. UserDescription? for example.
  • Method names should also be in CamelCase, with the initial character in lower case. getUserDescription() for example.

Indentation and Parenthesis

Each layer of indentation should be one tab (3 spaces) deep.

Parenthesis should be placed on their own line, at a level of indentation one above the enclosed code. If the enclosed code is only one line long, forgo the use of parenthesis altogether and keep everything on one line.

void exampleMethod()
{
        anotherMethod();
        if (something) doSomething();
        else
        {
                dontDoSomething();
                doSomethingElse();
        }
}

Spacing

A single space should be used to separate arguments. A single space should be placed either side of an operator, unless that operator has only one operand, ++ for example.

for (int i = 1; i < 10; i++)

Internationalisation Support

All strings in forms, will automatically be subject to extraction and replacement via our translation tools. However, developers need to flag strings within source code as translatable. This applies to any string the user is ever likely to see in the application, except debug messages sent to the CLI via qDebug().

To mark a string as translatable simply enclose it within the tr() method. For example:

“Unknown Setting” becomes tr(“Unknown Setting”)

Documentation

Developer documentation for your application should be placed into the development wiki. Each application should have a page of its own, and the page name should be equal to the subversion module name. To create a new page, simply visit trac.pcbsd.org/wiki/moduleName, trac.pcbsd.org/wiki/kcmPBSystem for example. If the page doesn't exist already, and you're logged in with wiki editing permissions, you'll be presented with the option to create the page.

You should provide the following information, as a minimum, for your application:

  1. The name of your application, and its intended purpose.
  2. A list of all the source files in your application, with a brief description of their role.
  3. A list of any external applications used, along with how and why they are used.
  4. A list of any external libraries used, with a brief description of what they're used for in your application.
  5. A list of configuration files your application uses, and what it stores in them.
  6. A list of registry entries you application reads and writes to, along with what is stored within them.

Any diagrams you can provide, UML or otherwise, should be included, but are not required.

Licensing

All code written for PC-BSD, should be BSD licensed.