root/trunk/licq/doc/README.CodingStyle

THIS README IS INTENDED FOR DEVELOPERS
======================================
 
(use 2 spaces for tab-stops to read/modify this document)
 
Who should read this?
  This document is written for people who do development on Licq.
  Everyone who modifies parts of the source is a potential developer
  and should read on :)
 
What is this README all about?
  This document describes the preferred coding and 
  documentation style for Licq and it's Plugins.
 
Why should i code and document my source in a special way?
  Many people develop on the same code and everyone wants 
  to easily read and understand it. You have your own style 
  of coding of course and we respect this fact. But when 
  you work on Licq sources you should respect our coding 
  style as well and anyways it's a great improvement when
  we all agree to a common style so that everyone can easily 
  read understand the code.

  The Documentation is generated automatically by a tool called
  Doxygen. It can provide descriptions and explanations for 
  every class/method/slot/attribute/you-call-it of the source.
  This is very comfortable, but requires the source code to be
  commented in a special (easy) manner.
  It's no big deal and the result is brilliant, believe me! :-)
 
Please also have a look at the Doxygen Website: http://www.doxygen.org
 
 
 
OK, WHAT ARE THE RULES? :)
==========================
 
 
 
        Indentation:
 
  Tabs are 2 characters, and thus indentations are also 2 characters.
  The idea behind indentation is to clearly define where a block 
  of control starts and ends. Please keep this in mind and use 
  indentation when it's useful.
 
 
 
        Placing braces:
 
  Braces are an issue that comes up everytime in C(++) styling.
  The preferred way to place braces for Licq developers is to
  place braces on a line of its own:

  if (x is true) 
  {
    we do y
  }
 
  The closing brace is put on a line of its own, too:

  if (x is true)
  {
    we do y
  }
  else
  {
    we do z
  }
 
 
 
        Naming:
 
  Always try to choose short names. But always ensure that the 
  name is descriptive enough to let code-readers know what the 
  name stands for. If you need a variable that stores a 
  temporary value, don't call it "ThisVariableIsATemporaryCounter",
  better call it "tmp".
  Use mixed case when you choose a descriptive name: "refCounter"
  the first character is always small.
  Put the object type in front of object name. In example a button 
  is called "btnClose", a multi-line-edit is called "mleMyLongText".
  Same applies to functions, methods and slots.
 
 
 
SOURCE DOCUMENTATION:
=====================
  Everything can get a brief and detailed description.
  You can add a brief (one-line) description by writing something
  like this:

    /*! \brief This is a short one-line description */
    void FooBar::slot_ok (bool bFoo)
    {
    }

  A detailed description can contain multiple lines and should 
  be written like this:
 
    /*! This is a detailed description of class FooBar.
    * Please notice that a detailed description is spreaded 
    * over multiple lines :)
    */
    void FooBar::FooBar (bool Foo, unsigned short Bar)
    {
    }

  The main difference between Doxygen and regulary C++ comments is the 
  additional exclamation mark (!).
  Every description is written directly in front of the declaration of
  the object you want do describe.
  Please also have a look at Doxygen's website:
  http://www.doxygen.org

  Take a look at this complete example:

  --- example ---
    /*! \brief creates a add-user dialog.
    *
    * A new dialog window is created by this class. It provides a 
    * QLineEdit which takes the UIN of the user who should be added.
    * In addition it contains a checkbox which indicates wether the 
    * remote user should be notified or not.
    */
    class AddUserDlg (CICQDaemon *s, QWidget *parent)
      : QDialog(parent, "AddUserDialog")
    {
    public:
      AddUserDlg();
      ~AddUserDlg();
    }
  --- /example ---
 
 
 
        What, where, how?
        -----------------
Classes:
    -> comments go inside *.h files
    -> always include a brief AND detailed description
 
Methods/Slots/ctor/dtor:
    -> comments go inside *.cpp files
    -> no brief, only detailed description
 
Attributes:
    -> comments go inside *.cpp OR *.h files
      (put your comment in front of the declaration, normally 
      this will be in the header file)
    -> a detailed description is sufficient
 
 
 
        EXAMPLES:
        ---------
 
 
 
Commenting a class:   ( myclass.h )
-------------------
 
  /*! \brief Here a brief one-line description :)
  *
  * And here begins the detailed description of MyDocumentedClass.
  * It consists of multiple lines and describes every important
  * thing regarding this Class!
  */
  class MyDocumentedClass (QWidget *parent, bool bFoo)
  {
  }
 
 
 
Commenting a Method/Slot/Constructor/Desctructor:    ( myclass.cpp )
-------------------------------------------------
 
  /*! \brief Here a brief one-line description :)
  *
  * And here begins the detailed description of the slot ok()
  * Every detailed description can be multiple lines long.
  */
  void MyDocumentedClass::slot_okButtonPressed()
  {
  }
 
 
 
Commenting Attributes:    ( myclass.cpp )
-----------------------
 
  /*! This QCheckBox indicates if we are cool or not */
  QCheckBox *chkAreWeCool;
  /*! This QLineEdit holds a value which is the UIN of the owner */
  QLineEdit *nUin;
 
 
OK, THAT'S IT!
==============
 
  Now close this doc and have
  fun with the code :)
 
  Thomas Reitelbach
  
  
  
  post scriptum:
  I borrowed the CodingStyle readme from the linux kernel tree
  while writing this document. Some parts may look similar.
  A big "thank you" goes to the kernel tree people :)

        post post scriptum:
        It is:
          if (x)
          {
            //
          }
 
        And NOT:
          if (x) {
          //
          }