kde-extraapps/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
================================================================================

Older versions of JuK had two different indenting schemes.  Now all JuK source
code 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.

Header guards should be of the form FILENAME_H, as below (for an example file
foo.h:

/* copyright/license stuff
 * blah
 */

#ifndef FOO_H
#define FOO_H

#include <qt stuff>

// classes

#endif

// vim modeline (see below)

================================================================================
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".

================================================================================
Editor Support
================================================================================

Most JuK files that Michael Pyne has touched will eventually have a vim modeline
at the bottom of the file (after any moc #includes).  The current vim modeline
is the following:

// vim: set et sw=4 tw=0 sta:

The vim: ... : part encloses the commands to automatically use when opening the
file in vim.  The following commands are set:
  et     : Uses spaces instead of the <TAB> when the Tab key is pressed.  No
           JuK source should have tab characters anymore, this helps enforce
	   that.  Full name is expandtab.
  sw = 4 : Makes indenting levels 4 spaces wide, for use with the vim indenting
           features.  Full name is shiftwidth.
  tw = 0 : Prevents vim from wrapping lines as you are typing.  Full name is
           textwidth.
  sta    : Use shiftwidth to determine tab size at the beginning of the line,
           instead of tabstop (which is normally 8 spaces wide).  Full name is
	   smarttab.

Also, vim users will want to have the command "let c_space_errors=1" in their
.vimrc in order to flag extra whitespace at the end of lines, which is also a
no-no in source code.

There are vim and emacs scripts for KDE developers in kdesdk/scripts, you may
also want to see what is available there.

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

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>