/*!
\page coderules FreeMedForms Coding Rules

\section coderule_intro Introduction

When several people are working on the same software, it is extremely important that they have a
common coding style for inter-readability and exchange.
Therefore we are publishing this "code rules" / "rules of conduct".

Before making any changes in the code or the FreeMedForms libs, it is essential
to discuss the intents on the mailing list (freemedforms@googlegroups.com). Any change made ​​without
consultation can induce unwanted and unexpected behavior on plugins or applications derived from
the base FreeMedForms.

\section headers Source headers

Each .h and .cpp file \e must contain the FreeMedForms header.

If you are writing some code that is inspired by some other (open source) software, you must include
the following paragraph in the header file (and where the software demands this else):

\verbatim
/***************************************************************************
 *   This code is inspired by NAME_OF_THE_SOFTWARE, VERSION                *
 *   URL_OF_THE_INSPIRING_SOFTWARE                                         *
 *   NAME_OF_ORIGINAL_AUTHOR, MAIL_ADRESS_OF_THE_ORIGINAL_AUTHOR           *
 *   LICENSE_OF_THE_ORIGINAL_SOFTWARE                                      *
 *                                                                         *
 *   Adaptations to FreeMedForms by:                                       *
 *       YOUR_NAME <MAIL@ADRESS>                                           *
 ***************************************************************************\/
\endverbatim

You can add a comment frame like below stating your participation.

\verbatim
/***************************************************************************
 *  Main Developer: NAME <MAIL@ADRESS>                                     *
 *  Contributors:                                                          *
 *       NAME <MAIL@ADRESS>                                                *
 *       NAME <MAIL@ADRESS>                                                *
 ***************************************************************************\/
\endverbatim

\section intendation Code Intendation

All code presented to the administrators of the suite must meet indentation rules as follows:
- One instruction per line
\code
//BAD:
if(blah){triggerHappyFunction();a++; whyNotThisAlso(new Foo("hello"),QString("bla %1").arg(x));}

//GOOD:
if (blah) {
    triggerHappyFunction();
    a++;
    const Foo *foo = new Foo("hello")
    whyNotThisAlso(foo, QString("bla %1").arg(x));
}
\endcode
- \b Four \b spaces (no tabs!) for each indentation
- A line of code which is too long for proofreading easily should be wrapped at ~80-100 characters.
There is no strict rule in this area, but do not hesitate to "break"
your line of code (line break + indentation) when it exceeds about
80-100 characters.
\code
OuterNamespace::Internal::FooClass::someStaticMethod("This is the first very long argument",
                                        otherMethod->toString(),
                                        thirdMethod->calculate());
\endcode
- Open curly brackets always on the \b same \b line for \b normal \b blocks (if, do, while, switch, etc.)
\code
if (test) {
    fooMethod();
    otherTest();
} else {
    barMethod();
}
\endcode
- Open curly brackets always on the \b next \b line for \b function \b blocks
\code
void foo(int blah)
{
    doSomething();
}
\endcode

- No unnecessary whitespace at the end of lines or at empty lines. There is a QtCreator feature
that automatically removes this whitespaceson saving files - just turn it on and you'll be fine.
- Don't change the value of variables in a function call
\code
//BAD:
getValue(i++);

//GOOD:
getValue(i);
++i;
\endcode

We prefer:
- well readable, "airy" code
- group code parts that belong together visually by separating them from others with newlines

Many IDEs can generally set the style of the code. Feel free to use these functions.\n
Read the code that is already there and try to submit your code in the same way.

\section export Exporter/Importer for win32

When you add a new class to FreeMedForms or one of its toolkits, make sure you export your class properly.
    - Include a file for import/export, which is properly called xxxxxxx_exporter.h
        - pluginname_exporter.h for FreeMedForms
        - libraryname_exporter.h for libraries
    - Then use the macro XXXX_EXPORT to import/export
        - \e CORE_EXPORT for objects within FreeMedForms
        - e.g. \e UTILS_EXPORT for libraries and plugins (here e.g. of the \e Utils library)

\Hint: If you use QtCreator, you can easily create these files automatically using the template wizards
that are provided with FreeMedforms.
<a href="http://www.freemedforms.com/en/code/howto_write_a_fmf_plugin">More information here</a>.

\section namespaces Naming rules for namespaces, classes, and class data

File names:
     - Should \b always be \b lowercase.
     - If necessary, create subdirectories in your plugins.

Classes:
- As meaningful as possible. Think about what exactly the class will do and name it very carefully. Don't
create clases like "PatientThings" etc. that don't explicitely tell the purpose of the class.
- Class names are \e CamelCased (first letter of each word constituting the class name is capitalized)
- Stereotypes
    - Postfixes:
        - 'Base' for databases managers: 'Base' after the database manager name
        - 'Dialog' or 'Model' for dialogs and models specific to a concrete class, e.g. a dialog
for class "Webcam" should be named "WebcamDialog"
        - 'Widget' for a widget
        - 'Plugin' for a plugin
        - etc.
    - Prefixes:
        - 'm_' for member variables
        - \b no prefix for methods
    - member variable and method names should be "camelCased", beginning with a \e lowercase
      letter (see example below).

Example:
\code
class YOUR_EXPORTER YourObject
{
public:
    YourObject();
    ~YourObject() {}

    void fooMethod(int value);
    bool isAvailable();
    [...]

private:
    int m_Handler;
    DrugsData *m_Drug;
    QMap<QString, QString> m_MapNameFirstname;
};
\endcode

\section objects Object Structure

- Public interfaces must be simple and clear.
- When a member is sufficiently general to apply to several subprojects of FreeMedForms,
it should be introduced in the global library 'Utils' (\e utils/global.h).
- When a whole object is general enough to be reused by other subprojects
it should be added to a library or a plugin (Editor for example).

\section dirs Directory structure

- The directory tree is fixed. Please respect this.

\section codedocumentation Code Documentation

We document our code with Doxygen. If you want to dive into howto document with Doxygen, look at the official
Doxygen documentation at <a href="http://www.doxygen.org">www.doxygen.org</a>.
- Generally should all methods have at least a single line documentation explaining the purpose.
- Complex functions \b must be documented.
To improve bugfixing please add the following framework documentation block in the header file of your
code (\e version is the release version of the object).

\e Hint: If you use QtCreator and create classes using the template wizards provided by FreeMedForms
this documentation part will be done automatically.

\verbatim
/**
 * \file nameofthecurrentfile.h
 * \author AUTHOR_NAME <MAIL@ADRESS>
 * \version 0.0.3
 * \date DATE_YYYY_MM_DD
 *\/
\endverbatim

A quick class descriptor is written \e in \e English in the upper part of the header file (.h) above the
class itself:
\verbatim
/**
 * \class Drugs::DrugsBase
 * \brief This class owns all information about the structure of the drugs database.
 *
 * All tables are described in an enum and a static QStringList.
 * Get fields and tables using \e getFields() and \e getTables().
 * Get where clauses using \e getWhereClause()
 *\/
\endverbatim


- Generally try to document code in the implementation (.cpp file), not in the header files.
This keeps the header files smaller (faster compile times) and cleaner.
- Comments are written using the C++ style '//'.
For convenience reasons, comments like
\verbatim
\/* comment *\/
\endverbatim
are used \e only by administrators to neutralize large portions of code in tests.

- Don't comment \e every single bit in your source code, it can affect the readability.
- Prefer variables and functions with meaningful names ('drugsCounter' rather than 'm1').
- It should be possible to read the code naturally, without much explanation. For example,
do not write a comment that the call to 'resetDatabaseValue()' will reset the database value - this is obvious by the name.
- The documentation is written in \e English \e only.
- Inclusions paths are defined in the project as following:
    - \e ./plugins
    - \e ./libs
    - \e ./contrib

- For reading convenience, use the following order for inclusion of headers:
    -# Plugins (grouped into blocks by plugins)
    -# FreeMedForms libraries (grouped into blocks by libraries)
    -# Qt headers

\code
#include <pluginname1/filename.h>
#include <pluginname1/subdir/filename2.h>

#include <pluginname2/filename.h>
#include <pluginname2/subdir/filename2.h>

#include <utils/log.h>
#include <utils/global.h>
#include <translationutils/constanttranslations.h>

#include <QString>
#include <QDate>
\endcode

\section interactions User Interface and Interaction with the User

\subsection messageboxes Using of MessageBox

- <b>QMessageBox should \u not be used.</b>
- The Utils library provides all the functions for your MessageBoxes.
    - void Utils::informativeMessageBox() (just with Ok)
    - bool Utils::yesNoMessageBox() (returns true if Yes)
    - bool Utils::okCancelMessageBox() (returns true if OK)
- A text with one to two sentences should briefly describe the message to the user.
- Information text and a detailed text can accompany this message.

\code
    // BAD:
    QMessageBox(...)

    // GOOD:
    Utils::okCancelMessageBox( tr("Text"),
                        tr("Informative"),
                        tr("Detailed text"),
                        tr("Title is faculative, application name will appear if no text is passed."));

    // If the Utils version doesn't fit your needs, please extend/subclass it and use the same model.
\endcode

\subsection i18n Internationalisation

- \e All user visible text must be written in simple and correct English, and translatable
using the functions \e tr() or \e QCoreApplication::translate().
- All widgets must be instantly translated when a new language is loaded by the application. To achieve this,
reimplement the method changeEvent() in the widget and query for QEvent::LanguageChange:
\code
void MyWidget::changeEvent(QEvent *e)
{
    if (e->type() == QEvent::LanguageChange)
        retranslate();
}
\endcode
Sometimes this is done automatically in auto-created code by QtCreator in the ui_mywidget.cpp file.
The class Form::FormItem already implements the i18n feature.

\section building OS Management and Compilation Mode

The Utils library provides functions for identifying the Operating system:
Utils::isRunningOn(). Where possible use these functions instead of using preprocessor instructions
(#ifdef Q_OS_MAC). Of course, if your code is highly specific to one OS, then the use of macros
will be ignored.
<i>//TODO: please correct from original: "Bien évidemment, si votre code est hautement spécifique à l'OS, alors l'utilisation
   des macros sera incontournable."</i>

Two functions are used to identify the application compilation mode: \e isDebugCompilation() and
\e isFullApplication(). These functions use macros defined in \e config.pri which is used by all
 FreeMedForms projects.

\section optimisations Optimisations

Optimized code is generally more prefered than unnecessarily cumbersome code. However, in general,
avoid writing 'highly optimized code' at the expense of readability and scalability;
we do not write a RTOS (RealTime Operating System), but the tools should not force your machine to
its knees :)

Do not choose objects for their performance, but for their specificity to a problem.
For example, to store a list of objects, QList is better than a QVector, although the latter
is more efficient in some cases.

Keep the optimization ideas for key locations and intensive use of specific parts of the application
(e.g. heavy manipulation of the database).

\subsection useforeach The Use of 'foreach'

It is preferable to use 'foreach' to iterate through a container. Whenever possible, create the
foreach variable as a constant reference (to limit copies in memory)

\code
foreach(const QString &s, stringList) {
    if (s.endsWith('.cpp'))  // OK
        useCppSource();
    s = s.trimmed(); // ERROR! not possible!
}
\endcode

*/
