Developer guidelines

Table of contents

• Preface
• Organization
• General rules
• Internationalization
• Documentation
• Legal
• Identation
• General naming conventions
• Variables
• Functions
• Classes
• Templates
• C++ Exceptions
• Whitespace
• Types
• Braces
• Switch statements
• Parentheses
• Line breaks
• Qt Includes
• Preprocessor

Preface

The following paragraphs describe some standard processes, behavior and tools. The coding standard is based on the Kdelibs coding style, the Qt coding style and the GNU coding standards The document is incomplete and everyone has different preferences. If you find something is missing or could be done better then please discuss it on the mailing list.

Organization

Development of ND-Bus has just been started and the ND-Bus Community currently consists of only one active member - that's me. So all all work is done by - you guessed it right - myself. I hope the community will soon grow. Until then I am the lonely dictator of ND-Bus. As soon as someone else joins the community ND-Bus will get a more democratic form of organization.

General rules

• Portability comes first. The primary purpose of ND-Bus is to connect applications on very different platforms, especially GNU/Linux, Windows and MacOS.
• Use C++ instead of any other programming language
• Use Qt instead of other toolkits
• When using C++ use Qt
• Avoid arbitrary limits on the length or number of any data structure, including file names, lines, files, and symbols, by allocating all data structures dynamically.
• Check every function call for an error return, unless you know you wish to ignore errors.
• Try to make all functions reentrant and thread safe
• Assume the targeted hardware has multiple CPUs. Try to create parallel algorithms instead of long sequential algorithms. Create multiple threads when it's worth the overall effort.
• A program shall not only write error messages to the terminal but also into a file
• If you need a some functionality and the language/toolkit you are using offers classes etc. to support this: Use them instead of reinventing the wheel.
• Everything has to be put under version control. This applies to source code and documentation. ND-Bus uses Git for this purpose. If you are not already familiar with SCM systems in general and with Git in particular, then please take an evening or evening two and read the Git manual and tutorial.

Internationalization

• With no exception use American English for every thing in source files and documentation.
• When programming with Qt use its abilities for translation of user interfaces.
• When programming in C use GNU gettext for internationalization if possible.
• It is mandatory to make translations of user interfaces possible, but poviding any actual translation is not a primary task
• Try to integrate unicode support

Documentation

• First of all: Raw / very short documentation is not good but better than nothing.
• Please don't think 'I can write the documentation for this function later'. As soon as you have a piece of working code and a more or less stable API, then please take the time and write the documentation for it. Otherwise it will become harder and harder to remember all details as days go by and you already have turned your attention to something else.
• I will not integrate any code into ND-Bus that has an incomplete API documentation. (Incomplete documentation of internals is acceptable to some degree).
• Documentation for developers must be supplied in American English
• End user documentation must also be supplied in American English. Translations to other languages are nice to have but not a primary task
• Use Doxygen for source code documentation when ever possible. Use Doxygen also for all other kind of documentation. Standard configuration files for Doxygen are provided by the ND-Bus Community.
• ND-Bus provides all documentation at least in HTML and PDF format. PS files and man pages should also be provided when it's not too much work.
• In general, prefer vector graphics to raster graphics.
• It is recommanded to use xfig for drawing vector graphics. Save your files always in the FIG-format and export them as PDF files to include them in the documentation.
• It is recommanded to use GIMP when you need to create/manipulate raster graphics. Always save your work in the XCF file format and export the image as PNG file to include them in the documentation.
• Don't forget to put your XFIG and XCF files under version control.

Legal

• All ND-Bus source code must be published under the terms of the current GPL
• All ND-Bus documentation must be published under the terms of the current GFDL
• All files must state an appropriet legal notice

Identation

• 4 Spaces, no tabs

General naming conventions

• Names start with a lowercase letter.
• Each new word in a name starts with a capital letter
• Avoid short names and abbreviations like 'randGetVal' or 'snd'
• Exceptions: The meaning of a short name is absolutely obvious or the name is e.g. a counter variable or similar temporary object
• If an abbreviation is part of a name then only the first letter is upper case, eg. getIpAddress and ipIsValid instead of getIPAddress and IPIsValid
• Exception: 'NDBus' must be written like this always.

Variables

• Each variable declaration on a new line
• Wait with declaring a variable until it is needed

Functions

• Forward declarations are mendatory
• Try to avoid pointers and use references
• In the parameter list the input-parameters come first, followed by combined input/output-parameters and output-parameters at last
• Try to avoid combined input/output-parameters.
• As a rule of thumb, a function should either return void if it can't fail anyhow, return bool if can fail and no further error handling is needed (false means error) or return int (qint32) where zero means success and anything else is a well documented error code.
• Avoid returning anything else, e.g. strings, without good reason.
• Exception: Class member function that simply return class private data etc.

Classes

• General naming conventions also apply to class declarations, but with the exception that class names start with a capital letter

Templates

• Use them

C++ Exceptions

• Don't use them

Whitespace

• Use blank lines to group statements
• Use only one empty line
• Use one space after each keyword
• For pointers or references, use a single space before '*' or '&', but not after
• No space after a cast

Types

• Use Qt types like qint32 instead of int where possible
• Avoid C-style casts when possible, use c++ casts
• Use QStrings instead of c-style strings
• Use Qt container classes instead of STL container classes
• Use STL-style iterators for Qt containers, not Java-style

Braces

• The left curly brace goes on the same line as the start of the statement.
• Use curly braces even when the body of a conditional statement contains only one line.
• Use curly braces when the body of a conditional statement is empty
• Exception: Function implementations, class, struct and namespace declarations always have the opening brace on the start of a line.

Switch statements

• Case labels are on the same column as the switch
• The default label is mentatory
• Every case must have a break (or return) statement at the end or a comment to indicate that there’s intentionally no break

Parentheses

• Use parentheses to group expressions
• Avoid assignments inside conditions

Line breaks

• Try to keep lines shorter than 100 characters, inserting line breaks as necessary.
• Commas go at the end of a broken line; operators start at the beginning of the new line.

Qt Includes

• If you add includes for Qt classes, use both the module and class name. This allows library code to be used by applications without excessive compiler include paths.

Preprocessor

• General rule: Avoid the use of the c preprocessor when ever possible
• Use enum types and constant types instead of defines
• Try to use if() statements with constant types instead of ifdef with defines when conditional compilation is needed; modern compilers will create exactly the them output but can perform more extensive type checking before.
• Exception: ifndef statements for header file protection are ok.
• Avoid function-like macros