# Coding Rules

Where-ever possible this document should be referred to when questions regarding the format of the source code are raised.

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.

## General

The following list shows the general rules that should be regarded by any developer working on &app;.

- 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.

- 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).

- All dialogs should be located in the kmymoney/dialogs directory.

- 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).

- All user visible text should be wrapped in the i18n internationalisation wrapper for translation.

## Header Files

The following rules apply to all header files.

- Header files shall end with the extension .h not .hpp.

- All header files shall begin with a comment block as generated by KDevelop.

- 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)

  ### Using include stoppers

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

- All classes designed for use by the KDE interface should begin with a K with each separate word beginning with an uppercase letter e.g KSomethingDlg.

- The header file will include other header files in the following fashion and same order:

  ### Including other header files

        //-----------------------------------------------------------------------
        // QT Headers
        #include <qtlabel.h>

        //-----------------------------------------------------------------------
        // KDE Headers
        #include <kcombobox.h>

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

- Each class should have a kdoc compatable comment header to describe the class and it's function within kmymoney.

- Classes shall begin their declaration as such:

  ### Class declaration

        class KSomethingDlg : public KBaseClass {

  with an appopriate access declared.

- 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.

  ### Complete class declaration

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

        private slots:

        protected:

        protected slots:

        public:
          KSomethingDlg();

        public slots:

        signals:
        };

- All slot methods should begin with slot and signal methods should start with signal. e.g

  ### Declaration of slot and signal methods

        signalFoundTransaction();
        slotFoundTransaction();

- 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:

  ### Attribute naming convention

        QComboBox m_qcomboboxMethod;
        int m_intCounter;
        int m_nCounter;

- 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.

## Source Files

The following rules apply to all source code files.

- C++ source files shall end with the extension .cpp not .cc or .cxx

- As with header files these should start with a header block similar to the one generated by KDevelop.

- Include files shall be included in the same format as for header file e.g

  ### Including header files in source files

        //-----------------------------------------------------------------------
        // QT Headers
        #include <qtlabel.h>

        //-----------------------------------------------------------------------
        // KDE Headers
        #include <kcombobox.h>

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

- Methods should be implemented as such:

  ### Method implementation

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

  with the function body indented by one tab (equals two spaces).

- Flow control statements should preferably follow the Kernighan & Ritchie style as such:

  ### Kernighan & Ritchie flow control style

        while (something_is_true) {
          operate on something;
        }

  although the following Allman style is acceptable:

  ### Allman flow control style

        while (something_is_true)
        {
          operate on something;
        }

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

  ### One line body flow control style

        while (something_is_true)
          operate;

- Local variables should not be prefixed by the m_ member prefix and should start with a prefix as discussed for the header file. For example:

  ### Local variable nameing convention

        QString qstringTemp;
        char *pszTemp;

- 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.