tdemultimedia/juk/HACKING

Since I tend to be one of the more pedantic people on coding style I'll provide
a bit of a reference here.  Please take a few minutes to read this as it will
save us both time when processing patches.

================================================================================
Indentation
================================================================================

The older files in JuK are indented using Qt-style.  The first level was 4
spaces, the second one tab, the third one tab followed by 4 spaces.  I'm not
particularly fond of this style anymore, but it used to be the Emacs default
when using the KDE Emacs scripts.

static void foo()
{
    if(bar()) // <-- 4 spaces
        baz() // <-- 1 tab
}

Newer files simply use 4 spaces at all levels.  In most cases the style of the
file currently being worked in should be followed.  So:

static void foo()
{
    if(bar()) // <-- 4 spaces
        baz() // <-- 8 spaces
}

================================================================================
Braces
================================================================================

Braces opening classes, structs, namespaces and functions should be on their own
line.  Braces opening conditionals should be on the same line with one notable
exception:  if the conditional is split up onto several lines then the opening
brace should be on its own line.  i.e.

class Foo
{
    // stuff
};

if(foo == bar) {
    // stuff
}

while(foo == bar &&
      baz == quux &&
      flop == pop)
{
    // stuff
}

static void foo()
{
    // stuff
}

Other exceptions include inline functions that are just returning or setting a
value.  However multiple statements should not ever be combined onto one line:

class Foo
{
public:
    String value() const { return m_value; }
};

Also conditionals / loops that only contiain one line in their body (but where
the conditional statement fits onto one line) should omit braces:

if(foo == bar)
    baz();

But:

if(baz == quux &&
   ralf == spot)
{
    bar();
}

================================================================================
Spaces
================================================================================

Spaces should not be used between the conditional / loop type and the
conditional statement.  They should also not be used after parenthesis.  However
the should be to mark of mathematical or comparative operators.

if ( foo == bar )
  ^ ^          ^

The marked spaces should be ommitted to produce:

if(foo == bar)

================================================================================
Header Organization
================================================================================

Member variables should always be private and prefixed with "m_".  Accessors may
be inline in the headers.  The organization of the members in a class should be
roughly as follows:

public:
public slots:
protected:
protected slots:
signals:
private: // member funtions
private slots:
private: // member variables

If there are no private slots there is no need for two private sections, however
private functions and private variables should be clearly separated.

The implementations files -- .cpp files -- should follow (when possible) the
same order of function declarations as the header files.

Virtual functions should always be marked as such even in derrived classes where
it is not strictly necessary.

================================================================================
Whitespace
================================================================================

Whitespace should be used liberally.  When blocks of code are logically distinct
I tend to put a blank line between them.  This is difficult to explain
systematically but after looking a bit at the current code organization this
ideally will be somewhat clear.

Also I tend to separate comments by blank lines on both sides.

================================================================================
Pointer and Reference Operators
================================================================================

This one is pretty simple.  I prefer "Foo *f" to "Foo* f" in function signatures
and declarations.  The same goes for "Foo &f" over "Foo& f".

================================================================================

There are likely things missing here and I'll try to add them over time as I
notice things that are often missed.  Please let me know if specific points are
ambiguous.

Scott Wheeler <wheeler@kde.org>