This is the oscar HACKING file. It details the current coding style that is being
used in this plugin. Thanks to Scott Wheeler for providing the skeleton I based this
file on

================================================================================
Code Documentation
================================================================================

Please add doxygen comments to the header files where appropriate. I don't expect
anyone to add comments for functions that they're overriding from the base class
but comments everywhere would be good.

Please comment parts of the code that might be unclear, need more thinking about,
reimplementing, etc. It will help people look for things to do if they want to help
out.

Please don't remove the kdDebug lines from any of the source files. If they're
excessive, either wrap them in an ifdef and put the ifdef in the soon to be
created oscardebug.h file so that they can be enabled and disabled at the will of
other developers or users. I also tend to use kdDebug statements to document
my code in the place of comments for the simpler sections. 

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

I use tabs to indent everything. When I say tabs, I mean the 'tab' character. Please
don't use 8 spaces to indent. Just hit the 'tab' key, and make sure that space indentation
is turned off in whatever editor you use. However, the exception to the indentation
rule is anything that's inside of a namespace block should not be indented.


static void foo()
{
	if ( bar() ) <-- 1 tab
        	baz(); <-- 2 tabs
}

namespace
{
class Foo
{
Q_OBJECT
public:
	Foo();
	~Foo();
};
}




vim or kate modelines that modify the way tabs are displayed are encouraged, as
long as they don't actually change the way tabs are saved to a file.

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

Braces opening classes, structs, namespaces, functions, and conditionals should be
on their own line. Here's an example: 

class Foo
{
    // stuff
};

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

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

static void foo()
{
    // stuff
}

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 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 )
  ^ ^          ^

is correct. However:

if(foo == bar)

is not.

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

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

public:
public Q_SLOTS:
protected:
protected Q_SLOTS:
Q_SIGNALS:
private: // member funtions
private Q_SLOTS:
private: // member variables

If there are no private Q_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 derived 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.

Parenthesis should be padded by spaces on one side. This is easier to illustrate in
an example:

void Client::foo() //correct
void Client::foo3( int, int, int ) //correct

void Client::foo(int, int, int) //incorrect
void Client::foo(int,int,int) //also incorrect

Operators should be padded by spaces in conditionals. Again, more examples to
illustrate

if (foo==bar)
m+=(n*2)-3;

should be:

if ( foo == bar )
m += ( n * 2 ) - 3;

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

Also, please note that since this library is based heavily off of Kopete's 
libgroupwise library that the coding style in certain files may not match what's
written in this document. Those files that don't match will be corrected eventually.

To make things easier on you, kate modelines are provided at the end of certain files
to help enforce the coding style. If you're using the new C S&S Indenter that will be in
KDE 3.4, I can provide a patch that will automatically implement the space padding around
parenthesis. Please mail me so I can send it to you.

Matt Rogers <mattr@kde.org>