You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
414 lines
8.3 KiB
414 lines
8.3 KiB
<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 & Design using UML, Bennet & 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 <qtlabel.h>
|
|
|
|
//-----------------------------------------------------------------------
|
|
// KDE Headers
|
|
#include <kcombobox.h>
|
|
|
|
//-----------------------------------------------------------------------
|
|
// 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 <qtlabel.h>
|
|
|
|
//-----------------------------------------------------------------------
|
|
// KDE Headers
|
|
#include <kcombobox.h>
|
|
|
|
//-----------------------------------------------------------------------
|
|
// 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 & Ritchie
|
|
style as such:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Kernighan & 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>
|