Hacking on Audioscrobbler
-------------------------

Please respect these guidelines when coding for Audioscrobbler, thanks!

* Where this document isn't clear, refer to Audioscrobbler 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:
    - Audioscrobbler 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 "container.h"
#include "debug.h"

#include <QObject>


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 playback.
 * @param offset Start playing at @p msec position.
 * @return True for success.
 */
virtual bool play( uint offset = 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 CONTAINER_H
#define CONTAINER_H

class Container : public QObject
{
    Q_OBJECT

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

    public slots:
        void foobar();
};

#endif /* CONTAINER_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;
}


Debugging
---------
debug.h contains some handy functions for our debug console output.

Usage:

To be updated by Erik.


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 Audioscrobbler developers
