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.

Of course, if the amount of code you wrote is small (less than, say, 50
or 60 lines) don't pay much attention to this file; just send the code
right away.


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.  This 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->fooBar;  // Right.
           return fooBar;        // 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.  (There's
no safe way in C++ to call a virtual method that gets overwriten by the
constructor's own class, since at the time the constructor is called,
the object has not been fully created yet.  Even if the right method
gets called, the "this" pointer in this method might point to
something that can't be used yet.)


Use references to improve speed:

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

Don't use pointers for this!  ("Out of scope" problem.)


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

     case 3:
          // ...
	  // Use the comment below if there's no "break" at the end:
          // Fall-through.

     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 everything from 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.)
