MaverickCodestylePolicy

Revision 1 as of 2010-04-07 23:40:44

Clear message

Summary

This specification defines what the code style for all Kubuntu-specific tools written in C++ should use moving forward.

Rationale

Deciding on a common code style will ensure that our C++-based apps remain readable and maintainable, so that anybody with a sound programming head could jump in on development for any Kubuntu app.

Scope and Use Cases

Use Cases

* Matt is a developer. Matt wishes to start contributing to Kubuntu, and just so happens to have C++ skills. The Kubuntu team is able to direct him to the apps we have written in C++, and Matt is pleasantly surprised at the consistent, readable coding style. Matt goes on to be a coding superstar, thanks to clean [s]living[/s] code.

* Amelia is a developer and core contributor to one of the applications that Kubuntu maintains. Unfortunately, she disappears in a bizarre gardening accident, leaving her project orphaned. Thanks to clean, consistent code, the rest of the Kubuntu is able to properly maintain the application in her abscence.

Implementation

* Similar to kdelibs and amarok style, the later being spec'd here: http://gitorious.org/amarok/amarok/blobs/master/HACKING/intro_and_style.txt

Formatting

* Spaces, not tabs * Indentation is 4 spaces * Lines should be limited to 90 characters * For pointer and reference variable declarations put a space between the type and the * or & and no space before the variable name. * For if, else, while and similar statements put the first bracket on the same line as the statement declaration, with the ending bracket lining up to the indentation of the statement declaration * Function and class definitions have their brackets on separate lines * A function implementation's return type is on its own line. * CamelCase.{cpp,h} style file names. * Qt 4 includes a foreach keyword which makes it very easy to iterate over all elements of a container. Use whenever possible.

Example: 

bool MyClass::myMethod(QStringList list, const QString &name)
    {
        if(list.isEmpty()) {
            return false;
        }

        /*
          Define the temporary variable like this to restrict its scope
          when you do not need it outside the loop. Let the compiler
          optimise it.
         */
        foreach(const QString &string, list) {
            kDebug() << "Current string is " << string << endl;
        }
}

Class, Function & Variable Naming

*Use CamelCase for everything. *Local variables should start out with a lowercase letter. *Class names are captialized *Prefix class member variables with m_, ex. m_trackList. *Prefix static member variables with s_, ex s_instance *Functions are named in the Qt style. It's like Java's, without the "get"

  • prefix.
    • A getter is variable()
    • If it's a getter for a boolean, prefix with 'is', so isCondition()
    • A setter is setVariable( arg ).

Includes

Header includes should be listed in the following order:

  • Own Header
  • Qt includes
  • KDE includes
  • Other library includes, if applicable
  • Own includes

They should also be sorted alphabetically, for ease of locating them. A small comment if applicable is also helpful.

Includes in a header file should be kept to the absolute minimum, as to keep compile times low. This can be achieved by using "forward declarations" instead of includes, like "class QListView;" Forward declarations work for pointers and const references.

TIP: Kate/KDevelop users can sort the headers automatically. Select the lines you want to sort, then Tools -> Filter Selection Through Command -> "sort".

In vim the same can be achieved by marking the block, and then doing ":sort".

Example: 

#include "MySuperWidget.h"

#include <QtGui/QGraphicsView>
#include <QtGui/QWidget>

#include <KDialogBase>    //baseclass
#include <KPushButton>    //see function...

#include <otherapi/header.h>

#include "KubuntuLibs.h"
#include "Awesomeness.h"
#include "TardisControls.h"

Comments

Comment your code. Don't comment what the code does, comment on the purpose of the code. It's good for others reading your code, and ultimately it's good for you too.

Comments are essential when adding a strange hack, like the following example: 

/** Due to xine-lib, we have to make K3Process close all fds, otherwise we get "device is busy" messages
  * Used by AmarokProcIO and AmarokProcess, exploiting commSetupDoneC(), a virtual method that
  * happens to be called in the forked process
  * See bug #103750 for more information.
  */
class AmarokProcIO : public K3ProcIO
{
    public:
    virtual int commSetupDoneC() {
        const int i = K3ProcIO::commSetupDoneC();
        Amarok::closeOpenFiles(K3ProcIO::out[0],K3ProcIO::in[0],K3ProcIO::err[0]);
        return i;
    }
};

For headers, use the Doxygen syntax. See: http://www.stack.nl/~dimitri/doxygen/

Example: 

/**
 * Start playback.
 * @param offset Start playing at @p msec position.
 * @return True for success.
 */
virtual bool play( uint offset = 0 ) = 0;

CategorySpec