diff options
Diffstat (limited to 'developer-doc/phb/coding.docbook')
| -rw-r--r-- | developer-doc/phb/coding.docbook | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/developer-doc/phb/coding.docbook b/developer-doc/phb/coding.docbook new file mode 100644 index 0000000..ca7da82 --- /dev/null +++ b/developer-doc/phb/coding.docbook @@ -0,0 +1,413 @@ +<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> |