[Uml-devel] Coding Style v1

[Gopala Krishna]

On Wed, Jul 9, 2008 at 9:41 PM, Andi Fischer <andi.fischer at hispeed.ch> wrote:
> Hi everybody,
> Some weeks ago Gopala was looking for a style guide, Ralf Habacker
> committed scripts for 'astyle' usage and then there is this rather
> long thread about the kdelibs coding style on kde-core-devel.
>
> This all made me writing a small Coding Style Document for Umbrello. We
> are a small group of developers and my hope is, that we can agree on a
> common style, which we can apply over time.

Hello Andi,
  Nice work, great initiative indeed. This document should be
distributed with the code as well.
I agree with most of them. I have added some points and some
clarifications below.
Please correct if anything is wrong.

>  6.) Use one space after each keyword [4].
>      Example:
>          if(   // wrong
>          if (  // correct

One small clarification, should there also be a space after and before
the opening and closing parenthesis ?
What about function calls with respect to the whitespace ?


>  7.) For pointers or references, use a single space after '*' or '&',
>      but not before.
>      Example:
>          T* v and T& v
>      Rationale:
>          This is C++ style.
>          With rule 13,
>              char* i, j;  // i is declared pointer to char, while j is
> declared char
>          should not be possible.

So, isn't "char *i, j;" better than "char* i, j;" ?
I feel placing the '*' just before variable name and having a space
after the <datatype> is more clear.

>  8.) No space after a cast [4].

I feel the following could be added as well.
"
Use c++ style cast like static_cast, dynamic_cast instead of C-style
cast as it asserts the purpose of the cast.
Also try to use qt casts like qobject_cast, qgraphicsitem_cast in
place of dynamic_cast wherever possible as the
qt style casts succeeds even across libraries.
It doesn't mean dynamic casts shouldn't be use though. Use them
wherever it is impossible to use qt's cast.
"


>  21.) Member variables start with "m_".
>  22.) Variables (objectName) in ui files start with "ui_".
>      Rationale:
>          This makes it possible to identify the source of the variable
>          (defined in class or in ui file).

Also I would opt not to use pseudo Hungarian style like
m_bSomeBoolean, m_pSomePointer because it really makes typing hard.
m_whatever is best I feel.


> Includes:
> ---------
>  26.) Include own header first (checked by Krazy [6]).
>  27.) Use QtModule/QClass in angle brackets (checked by Krazy [6]).
>  28.) Use KDE/KClass in angle brackets (checked by Krazy [6]).
>  29.) Do not add a path to the include statement.
>      Example:
>          #include "../uml.h"  // wrong
>      #include "uml.h"     // correct
>      Rationale:
>          Paths are set in the make files. Rearranging or moving files
>          should not be followed by source code editing.
>

Just to clarify more, I found these lines in amarok HACKING guidelines {1}
I have modified one or two lines here.
"
Header includes should be listed in the following order:
    - Own Header
    - Umbrello 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".

In vim the same can be achieved by marking the block, and then doing ":sort".
In emacs, you can mark the block and then do "M-x sort-lines". (added by me ;) )
"

> Doxygen comments:
> -----------------
>  32.) Every public item must have a doxygen comment.
>  33.) Doxygen comments look like (see also [9]):
>      /**
>       * Here is the description...
>       * @param ...   ...
>       * @return      ...
>       */
>  34.) The comments should be written in the implementation file (cpp).
>      Rational:
>          The header files can be overviewed easier and read quicker.

I am in a dilemma whether to write the comments in cpp file even for
inline functions & classes using @fn and @class tags
or
to comment inline documents in header file itself.
The first one ensures uniformity while the second one provides convenience.


Also, "const correctness" should be preserved as much as possible.
Make all getters const.

Finally, it might be good idea to make the constructors explicit.

{1} http://websvn.kde.org/trunk/extragear/multimedia/amarok/HACKING/intro_and_style.txt?revision=822213&view=markup

-- 
Cheers,
Gopala Krishna A