Hacking on KMLDonkey
-----------------

Please respect these guidelines when coding for KMLDonkey, thanks!

* Where this document isn't clear, refer to KMLDonkey code.
* Avoid large commits of formatting fixes, as they easily cause merge conflicts.


This C++ FAQ is a life saver in many situations, so you want to keep it handy:

  http://www.parashift.com/c++-faq-lite/


Formatting
----------
* Spaces, not tabs
* Indentation is 4 spaces
* Lines should be limited to 90 characters
* Spaces between brackets and argument functions
* 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 brackets on the next line,
  although brackets are not needed for single statements.
* Function and class definitions have their brackets on separate lines

Example:

bool MyClass::myMethod( QPtrList<QListViewItem> items, const QString &name )
{
    if( items.isEmpty() )
        return false;

    foreachType( QPtrList<QListViewItem>, items )
    {
        (*it)->setText( 0, name );
        debug() << "Setting item name: " << name << endl;
    }
}

Header includes should be listed in the following order:
    - KMLDonkey includes
    - KDE includes
    - Qt 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".


Example:

#include "kmldonkey.h"
#include "debug.h"

#include "kdialogbase.h"    //baseclass
#include "kpushbutton.h"    //see function...

#include "qlistviewitem.h"
#include "qwidget.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!
For headers, use the Doxygen syntax. See: http://www.stack.nl/~dimitri/doxygen/

Example:

/**
 * Start something.
 * @param foobar This variable contains foobar.
 * @return True for success.
 */
virtual bool something( uint foobar = 0 ) = 0;


Header Formatting
-----------------
General rules apply here.  Please keep header function definitions aligned nicely,
if possible.  It helps greatly when looking through the code.  Sorted methods,
either by name or by their function (ie, group all related methods together) is
great too.


#ifndef __KMLDONKEY_DOWNLOADPAGE_H__
#define __KMLDONKEY_DOWNLOADPAGE_H__

class Foo : public Bar
{
        Q_OBJECT

    public:
        Foo( QWidget *parent, const char *name = 0 );
        ~Foo() {};

    public slots:
        void    fooBarOne();
        void    fooBarTwo();
};

#endif /* __KMLDONKEY_DOWNLOADPAGE_H__ */


0 vs NULL
---------
The use of 0 to express a null pointer is preferred over the use of NULL.
0 is not a magic value, it's the defined value of the null pointer in C++.
NULL, on the other hand, is a preprocessor directive (#define) and not only is
it more typing than '0' but preprocessor directives are less elegant.

    SomeClass *instance = 0;


Const Correctness
-----------------
Try to keep your code const correct. Declare methods const if they don't mutate the object,
and use const variables. It improves safety, and also makes it easier to understand the code.

See: http://www.parashift.com/c++-faq-lite/const-correctness.html


Example:

bool MyClass::isValidFile( const QString& path ) const
{
    const bool valid = QFile::exist( path );

    return valid;
}


Errors & Asserts
----------------
*Never use assert() or fatal(). There must be a better option than crashing a user's
application (its not uncommon for end-users to have debugging enabled).


Copyright
---------
To comply with the GPL, add your name, email address & the year to the top of any file
that you edit. If you bring in code or files from elsewhere, make sure its
GPL-compatible and to put the authors name, email & copyright year to the top of
those files.


Thanks, now have fun!
  -- the KMLDonkey developers
