kde-extraapps/akregator/HACKING

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

We use 4 spaces instead of tabs everywhere.

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

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

Opening braces should always be on their own line.

class Foo
{
    // stuff
};

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

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

static void foo()
{
    // stuff
}

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; }
};

Same goes for the main namespace of a header (the namespace where the class 
declaration is in, opposed to forward declaration (see also "Namespaces")
        
================================================================================
Spaces
================================================================================

Spaces should be used between the conditional / loop type and the
conditional statement. They should 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
================================================================================

Guards:
        
For test.h, declaring the class Akregator::Test, use AKREGATOR_TEST_H, not TEST_H,
nor _AKREGATOR_TEST_H_ etc. Comment the closing #endif.

#ifndef AKREGATOR_TEST_H
#define AKREGATOR_TEST_H
...
#endif // AKREGATOR_TEST_H
        
Member variables should always be private or protected 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 typedefs:
public ctors/dtors:
public methods:
public slots:
signals:
protected methods:
protected slots:
protected fields:
private ctors/dtors:
private methods:
private slots:
private fields:


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 derived classes where
it is not strictly necessary.

================================================================================
Namespaces
================================================================================

- Do not indent stuff in the "main namespace" of a file. But do for forward declarations.
- comment the closing bracket of the namespace with // namespace Foo

Example:
        
namespace KParts
{
    class ReadOnlyPart;
}
namespace Akregator {

class Foo
{
};

} // namespace Akregator

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

Use "Foo* f" and "Foo& f" in function signatures and declarations. And also in 
signal/slot names.

================================================================================
Signals and Slots
================================================================================

Prefix slots/signals with "slot"/"signal". Fully qualify types used in arguments
(i.e. add namespaces).

Example:
        
Use
        
    signals:
        
        signalFoo(const Akregator::Article&);
        
not
        
    signals:
        
        foo(const Article&);

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

An example object here:

test.h:
#ifndef AKREGATOR_TEST_H
#define AKREGATOR_TEST_H

#include "localinclude.h"
#include "anotherlocalinclude.h"
#include <kdeinclude1.h>
#include <kdeinclude2.h>
#include <qtinclude1.h>
#include <qtinclude2.h>

class QSomething;

namespace Akregator {

class Test : public QObject
{
    Q_OBJECT

    public:
        typedef QValueList<Test> list;

        Test();
        Test(QString someString);
        explicit Test(int i = 0);

        virtual ~Test();

        void someFunc();
        void someFunc2(QSomething *foo);

        static Test *instance() { return m_instance; }

    public slots:
        void receive(QSomething &);

    signals:
        void send(QSomething &);

    protected:
        void someProtectedFunc();

        static void someProtectedStaticFunc();

    protected slots:
        void protectedSlot();

    protected:
        int m_protectedVar;

    private:
        int privateMethod();

        static int staticPrivateMethod();

    private slots:
        void privateSlotIndeed(int youWonder);

    private:
        int m_privateVar;
        QSomething* m_tastyThing;

        static Test* m_instance;
};

} // no ; after namespace (borks on gcc 3.4+)

#endif

test.cpp:
#include "test.h"
#include "localinclude.h"
#include "anotherlocalinclude.h"
#include <kdeinclude1.h>
#include <kdeinclude2.h>
#include <qtinclude1.h>
#include <qtinclude2.h>
#include <qsomething.h>

namespace Akregator {

Test::Test()
    : QObject()
    , m_protectedVar(0)
    , m_privateVar(0)
    , m_tastyThing(0)
    , m_instance(0)
{
}

Test::Test(QString someString)
    : QObject()
    , m_protectedVar(0)
    , m_privateVar(0)
    , m_tastyThing(someString)
    , m_instance(0)
{
}

Test::Test(int i);
    : QObject()
    , m_protectedVar(0)
    , m_privateVar(0)
    , m_tastyThing(i)
    , m_instance(0)
{
    if (i == 0)
        kDebug() << "Zero initializer";
}

} // namespace Akregator

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

Original document by
Scott Wheeler <wheeler@kde.org>

Amendments for Akregator needs by
Stanislav Karchebny <stanislav.karchebny@kdemail.net>
Frank Osterfeld <osterfeld@kde.org>