If you want to send me code, please use the same coding-style in which
the rest of the sources are written.  This isn't *absolutely*
necessary, but it will save me some work.  This file documents the
style you should use.


QTads coding standard
=====================

When a string is supposed to be read by the user, use the tr() method:

  QMessageBox::warning(0, "Bla bla.", /* ... */);              // Wrong
  QMessageBox::warning(0, QObject::tr("Bla bla."), /* ... */); // Right

This allows for internationalization using the Qt tools `lupdate',
`lrelease' and Qt Linguist.  Read the Qt documentation for more details
(section "Internationalization with Qt").


Indent code with tabs, not spaces.  This allows me to set the tab-width
to 8 regardless of the width you use in your own editor.  It also
decreases the size of source files.


Lines should not contain more than 95 characters.  Comments should not
go beyond the 72th column.  Example:

   // This comment tries to explain what the function below is supposed
   // to do.  Okay then; it does nothing since it's only an example.
   thisFunctionHasAVeryLongOhSoVeryVeryLongAndHardToRememberName( int a, int b, QString c,
                                                                  bool d, bool e, char f );

The 72th column limit makes comments easier to read.  The 95 characters
limit serves two purposes; a) it helps me reading the code with my
96x41 text-only framebuffer display, and b) it serves as an indication
that the nesting level of a piece of code is too deep; if you have
nested so deep that 95 characters are not enough, you probably are
doing something wrong.


Use pure ANSI C++ (no GCC specific stuff; QTads is supposed to compile
with every compiler Qt supports).


Don't include headers just because a function or method prototype uses
types from it.  Use forward declarations instead.  This speeds up
compilation.  Do not use this:

    #include <qlabel.h>
    void
    foo( const QLabel& label );

but rather this:

    class QLabel;
    void
    foo( const QLabel& label );

It's up to the function's/method's user code to include <qlabel.h> if
it needs to.  Since my computer *is slow*, compilation speed is an
issue.


Function/method headers should look like this:

   int
   SomeClass::foo( int a, bool b, char c )
   {
           // ...
   }

   bool
   bar()
   {
           // ...
   }

Function-calls as usual:

   foo(x, y, z, z, y);
   int bar = xyzzy(*frotz);

Since Qt-signals never return values, their return type is always void.
Therefore, it isn't necessary to put the return type on a different
line.  Just declare signals like this:

   void someSignal( someType );


Pointers and references should be declared like this:

   int* foo;

   void
   xyzzy( int* foo, bool& frotz );

not:

   int *foo;

   void
   xyzzy( int *foo, bool &frotz );


Don't declare variables of the same type like this:

   int foo, bar;

but like this:

   int foo;
   int bar;

This avoids the "int* foo, bar" pitfall when what you mean is "int
*foo, *bar" and also makes the code easier to read.


Classes:

   class SomeClass: public QWidget {
           Q_OBJECT

     private:
           int fMember1;
           int fMember2;

           int
           fSomeMethod();

     protected:
           int member1;
           int member2;

           int
           someMethod();

     public:
           int
           method1( int a, int b );

           bool
           method2();

           virtual char
           method3()
           {
                   // ...
           }

     signals:
           void someSignal( bool );

     private slots:
           // ...

     protected slots:
           // ...

     public slots:
           // ...
   };


Private data-members should begin with `f' ("field"; an old Object
Pascal convention) and have the next character capitalized (as you can
see in the example above).


Use `this' even if it's obvious what you mean:

   int
   SomeClass::someFunction()
   {
           return this->fFooBar;  // Right.
           return fFooBar;        // Wrong.
   }

This makes it easy to tell what is a class member and what not, without
having to even read the identifier.


If you need to call methods from a base class in a constructor, use a
full qualifier.  If, for example, the base class is called Foo and you
want to call the method bar():

   Foo::bar();   // Right.
   bar();        // Wrong.
   this->bar();  // Wrong.

This is to ensure that the right method is called in case the method is
virtual; in C++, it's not a good idea to call overriden virtual methods
in a constructor.  Using the above technique makes it safe.


Use references to improve speed:

   QString tmp(someFunction(foo));          // Wrong.
   const QString& tmp = someFunction(foo);  // Right.


Never put a "using" at global scope!  Wrong:

   using std;
   void
   foo( vector<int> v );

Right:

   void
   foo( std::vector<int> v );


switch-statements:

   switch (x) {
     case 1:
           // ...
           break;

     case 2: {
           int a = 0;
           // ...
           break;
     }

     default:
           // ...
           // The break-statement can be omitted.
   }


Bicapitalize identifiers:

   int variableWithLongName;    // Correct.
   int variable_with_long_name; // Wrong.

   void
   crashTheSystem();   // Correct.

   void
   crash_the_system(); // Wrong.


Don't use `goto'!  Please!  Never!


If a namespace has only function-prototypes, indent them:

   namespace TheFoo {

           int
           foo();

           int
           bar();

   }

but if the functions also have implementations, then don't indent them:

   namespace TheFoo {

   int
   foo()
   {
           // ...
   }

   } // namespace TheFoo


Use the C++ STL for everything except strings and chars (use QString
and QChar).  For example, if you feel like using a

   int foo[100]

you should use

   std::vector<int> foo

instead, since the speed is the same but `vector' is safer.

You can also use the standard C library (since it's part of C++).

Never give a damn about non-ANSI compilers (but *do* give a damn about
bugs in compilers that are supposed to be ANSI; gcc 2.x for example.)