path: root/developer-doc/phb/coding.docbook

<chapter id="coding-std">
<title>Coding Rules</title>
<para>
Where-ever possible this document should be referred to when questions
 regarding the format of the source code are raised. 
</para>

<para>
By the way, we know the code doesn't always conform to the standards at
the moment, but work is underway to change the code and all new code
submitted should conform to the standards.
</para>

<!-- SECTION =================================================== -->
<sect1 id="general">
<title>General</title>
<para>
The following list shows the general rules that should be regarded by any
developer working on &app;.
</para>

<itemizedlist>
<listitem>
<para>
Each file should contain only one declaration or implementation and the
filename should reflect the class name. e.g ksomethingdlg.h would contain a
declaration for the KSomethingDlg class.
</para>
</listitem>

<listitem>
<para>
A tab width of 2 spaces should be used and if your editor supports it, the
tabs should be changed into spaces. (KDevelop/KWrite supports tab
translation).
</para>
</listitem>

<listitem>
<para>
All dialogs should be located in the kmymoney2/dialogs directory.
</para>
</listitem>

<listitem>
<para>
Each class should be as self contained as possible. If for instance, you
are creating a dialog, then all the signals and slots should be connected
within that dialog class. Where access is needed to the class details
methods should be used. This enhances readability and makes maintenance a
lot easier with each object having it's own state, indentity and behaviour,
(see Object Oriented Analysis &amp; Design using UML, Bennet &amp; Co).
</para>
</listitem>

<listitem>
<para>
All user visible text should be wrapped in the i18n internationalisation
wrapper for translation.
</para>
</listitem>
</itemizedlist>

</sect1>


<!-- SECTION =================================================== -->
<sect1 id="header-files">
<title>Header Files</title>
<para>
The following rules apply to all header files.
</para>

<itemizedlist>
<listitem>
<para>
Header files shall end with the extension .h not .hpp.
</para>
</listitem>

<listitem>
<para>
All header files shall begin with a comment block as generated by KDevelop.
</para>
</listitem>

<listitem>
<para>
The remainder of the header file shall be surrounded by include stoppers.
The name of the macro used should be the capitalized filename with the dot
replaced by an underbar (e.g. KSettingsDlg.h --\> KSETTINGSDLG_H)
<example>
<title>Using include stoppers</title>
<screen>

  #ifndef KSETTINGSDLG_H
  #define KSETTINGSDLG_H
    /* remainder of header file */
  #endif // KSETTINGSDLG_H


</screen>
</example>

</para>
</listitem>

<listitem>
<para>
All classes designed for use by the KDE interface should begin with a 
<emphasis>K</emphasis>
with each separate word beginning with an uppercase letter e.g
KSomethingDlg.
</para>
</listitem>

<listitem>
<para>
The header file will include other header files in the following fashion
and same order:
</para>

<example>
<title>Including other header files</title>
<screen>

  //-----------------------------------------------------------------------
  // QT Headers
  #include &lt;qtlabel.h&gt;

  //-----------------------------------------------------------------------
  // KDE Headers
  #include &lt;kcombobox.h&gt;

  //-----------------------------------------------------------------------
  // Project Headers
  #include "mymoney/mymoneyfile.h"


</screen>
</example>
</listitem>

<listitem>
<para>
Each class should have a kdoc compatable comment header to describe the
class and it's function within kmymoney2.
</para>
</listitem>

<listitem>
<para>
Classes shall begin their declaration as such:
</para>

<example>
<title>Class declaration</title>
<screen>

  class KSomethingDlg : public KBaseClass {


</screen>
</example>

<para>
with an appopriate access declared.
</para>
</listitem>

<listitem>
<para>
Access modifiers should be left flushed in the class declaration with all
attributes and methods indented by one tab. The access methods will be in
order starting with private. The access identifier should exist even if no
attributes or methods exist. Only one identifier can exist of the same
type. 
</para>

<example>
<title>Complete class declaration</title>
<screen>

  class KSomethingDlg : public KBaseClass {
  private:
    QString m_szSomeString;
    void useString(void);

  private slots:

  protected:

  protected slots:

  public:
    KSomethingDlg();

  public slots:

  signals:
  };


</screen>
</example>
</listitem>

<listitem>
<para>
All slot methods should begin with slot and signal methods should start with
signal. e.g 
</para>

<example>
<title>Declaration of slot and signal methods</title>
<screen>

  signalFoundTransaction();
  slotFoundTransaction();


</screen>
</example>
</listitem>

<listitem>
<para>
<anchor id="attribute-names"/>
Attribute names should begin with the m_ prefix to indicate that they are
member variables. The variable name should begin with a descriptive
identifier such as qcomboboxMethod. Explicit hungarian notation is also
fine. Examples of valid variable names can be found below:
</para>

<example>
<title>Attribute naming convention</title>
<screen>

  QComboBox m_qcomboboxMethod;
  int m_intCounter;
  int m_nCounter;


</screen>
</example>
</listitem>

<listitem>
<para>
Method names should specify a return and argument(s) unless used in a slot
or signal where the argument list can be left blank if necessary. The
method should start with a lower case letter with each subsequent word
having an upper case start letter.
</para>
</listitem>
</itemizedlist>

</sect1>

<!-- SECTION =================================================== -->
<sect1 id="source-files">
<title>Source Files</title>
<para>
The following rules apply to all source code files.
</para>

<itemizedlist>
<listitem>
<para>
C++ source files shall end with the extension .cpp not .cc or .cxx
</para>
</listitem>

<listitem>
<para>
As with header files these should start with a header block similar to the
one generated by KDevelop.
</para>
</listitem>

<listitem>
<para>
Include files shall be included in the same format as for header file e.g 
</para>

<example>
<title>Including header files in source files</title>
<screen>
  //-----------------------------------------------------------------------
  // QT Headers
  #include &lt;qtlabel.h&gt;

  //-----------------------------------------------------------------------
  // KDE Headers
  #include &lt;kcombobox.h&gt;

  //-----------------------------------------------------------------------
  // Project Headers
  #include "mymoney/mymoneyfile.h"
  #include "ksomethingdlg.h"


</screen>
</example>
</listitem>

<listitem>
<para>
Methods should be implemented as such:
</para>

<example>
<title>Method implementation</title>
<screen>

  void KSomethingDlg::useString(void)
  {
    .. function body
  }


</screen>
</example>

<para>
with the function body indented by one tab (equals two spaces).
</para>
</listitem>

<listitem>
<para>
Flow control statements should preferably follow the Kernighan &amp; Ritchie
style as such:
</para>

<example>
<title>Kernighan &amp; Ritchie flow control style</title>
<screen>

  while (something_is_true) {
    operate on something;
  }


</screen>
</example>

<para>
although the following Allman style is acceptable:
</para>

<example>
<title>Allman flow control style</title>
<screen>

  while (something_is_true)
  {
    operate on something;
  }


</screen>
</example>

<para>
It is also acceptable for one line body statements to omit the curly braces
as such: 
</para>

<example>
<title>One line body flow control style</title>
<screen>

  while (something_is_true)
    operate;


</screen>
</example>
</listitem>

<listitem>
<para>
Local variables should not be prefixed by the m_ member prefix and should
start with a prefix as discussed for the
<link linkend="attribute-names">header file</link>.
For example:
</para>

<example>
<title>Local variable nameing convention</title>
<screen>

  QString qstringTemp;
  char *pszTemp;


</screen>
</example>
</listitem>

<listitem>
<para>
Each method should have a comment block preceeding it in a suitable format
for other developers to see how the method works and what types of return
and arguments it expects. It does not have to be kdoc compatable because
kdoc only parses the header files. All kdoc comment blocks should be in the
header files.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>