Project

General

Profile

{{lastupdated_at}} par {{lastupdated_by}}.

1. Indentation

  • Indentation de 4 espaces ;
  • Remplacer toutes les tabulations par des espaces.

2. Includes

Si vous utilisez des directives d'inclusion pour des classes Qt, utilisez le module et le nom de la classe. Ceci permet au code de la bibliothèque d'être utilisé par des applications sans devoir avoir des chemins d'inclusions excessifs.


#include <QtCore/QString>

Pour les classes de QExtend, l'inclusion se fait sur le même schéma.

Exemple :


#include <Gui/Qss/MaClasse>

3. Conventions de nommage des modules

  • Lorsque c'est un module Qt, on reprend le nom en enlevant Qt :
    QtCore Core
    QtGui Gui
    Qtxxx Xxx
  • Lorsque c'est une bibliothèque externe, on reprend son nom ou ses initiales :
    qwt Qwt
    opencv OpenCv
    devil DevIL
  • Lorsqu'il s'agit d'un wrapper autour de plusieurs bibliothèques externes, on crée un module pour rassembler tous ces wrappers, module subdivisé par bibliothèque :
    Maths
      MPIR
      MPFR
    

4. Fichiers d'en-tête et de code

  • Les fichier sources, utiliser l'encodage UTF-8 sans BOM ; pour info, comme il n'y a pas de BOM, si le fichier ne contient que des caractères ANSI sur 7bits, les éditeurs considèrent que c'est de l'ANSI ;
  • Pour convertir les chaînes de caractère type C en QString, utiliser QString::fromUtf8 :

QString = QString::fromUtf8( "hello word" )

  • Si la chaîne C peut être traduite, utiliser la fonction trUtf8 :

myLabel->setText ( trUtf8( "hello word" ) )

  • Le nom et le chemin doivent être explicites et en minuscules ;
  • Les fichiers cpp et hpp sont dans le même sous-répertoire de src ;
  • Les en-têtes sont des fichier *.hpp :

src/gui/qss/dynamiqueproperty.hpp

  • Les code sources sont des fichier *.cpp :

src/gui/qss/dynamiqueproperty.cpp

  • Un header sans .hpp est ajouté dans le repertoire include/QExtend pour référencer le .hpp

include/QExtend/Gui/Qss/DynamiqueProperty

#include "../../../src/gui/qss/dynamiqueproperty.hpp
  • Sauf cas particulier, définition d'une seule classe par fichier ;
  • Tous les fichiers doivent commencer par cet avertissement de licence, en commentaire (modifier "nom du créateur du fichier") :
    Copyright © 2010  "nom du créateur du/des fichier" 
    
    This file is part of QExtend.
    
    QExtend is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    any later version.
    
    QExtend is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with QExtend.  If not, see <http://www.gnu.org/licenses/>.
    

6. Règles de codage

  • Espace de noms : QExtend ;
  • Nom des classes : CamelCase, ne jamais préfixer ses classes par Q ;
  • Nom des fonctions : camelCase ;
  • Membres publics en camelCase ;
  • Membres privés et protégés commençant par m_ en camelCase ;
  • Noms des membres sont alignés ;
  • Variables locales en cameCase ;
  • Ne jamais définir plusieurs variables sur la même ligne ;
  • Si on définit plusieurs variables locales une après l'autre, on les aligne ;
  • Si une variable est un pointeur ou une référence, on place le & ou le * collé au nom.
  • Les membres et fonctions d'une classe sont définies dans cette ordre :
  1. private
    1. variables membres
    2. méthodes
  2. protected
    1. variables membres
    2. méthodes
  3. public
    1. variables membres
    2. méthodes
  4. private Q_SLOTS
  5. protected Q_SLOTS
  6. public Q_SLOTS
  7. Q_SIGNALS

Exemple :


namespace QExtend
{

class MaClasse
{
    QString   m_text;
    int       m_a;
    int       m_b;
    int       *m_c;
    double    &m_d
/*...*/
public :
    void maFonction(QString &);
/*...*/

};

}
/*....*/

void maFonction(QString & s)
{
    QString   m_text;
    int       m_a;
    int       m_b;
    int       *m_c;
    double    &m_d;

/*...*/
}

  • Le style de formatage et d'indentation est basé sur le style Allman (aussi nommé ANSI ou BSD) ;
  • Toujours mettre le code entre accolades après toute structure de langage nécessitant un bloc de code (if, for...), même si ce n'est qu'une ligne de code.

int Foo( bool isBar )
{
    if ( isBar )
    {
        bar();
        return 1;
    }
    else
    {
        return 0;
    }
}   
  • Insérer des espaces autour des parenthèses des deux côtés, à l'intérieur et à l'extérieur ;
  • Insérer des espaces autour des opérateurs, sauf à l'intérieur de [] :

if ( isFoo ( a, b ) )
    bar ( a, b );

if ( foo == 2 )
{
     a = bar( ( b - c ) * a , * d-- );
}
  • Indenter de manière continue par rapport à la ligne précédente ;
  • Si une fonction a beaucoup d'arguments ou que le paramère est long, utiliser plusieurs lignes :

fooArray[] = { 
                  red,
                  green,
                  blue 
              };

fooFunction
       (
            barArg1,
            barArg2,
            barArg3
       );
  • Si une condition ou une opération est grande, utiliser plusieurs lignes :

if 
(
    a < b
    || 
    c > d
)
{
    a = 1 
        + 
        foo()
        + 
        (
            bar() 
            - 
            10
         ) 
         / 
         10 ;
}
  • Si vous utilisez l'operateur << et que la ligne de code est grande, utilisez plusieurs lignes en les alignant :

QStringList list;
list << "hello" 
     << "foo" 
     << "bar";
  • L'inclusion multiple est protégée grâce à des directives du préprocesseur. On utilise le nom du fichier en majuscules et en remplaçant le . par _ et en préfixant par QEXTEND_ ;
  • Ne pas écrire directement le namespace dans le fichier, itiliser les macro définies dans qextend_global ;
  • Pour exporter/importer des classes ou fonctions de la DLL, utiliser la macro QEXTEND_EXPORT définie dans qextend_global :

#ifndef QEXTEND_MACLASS_H
#define QEXTEND_MACLASS_H
QE_BEGIN_NAMESPACE

class QEXTEND_EXPORT MaClass
{
/*...*/
};

QE_END_NAMESPACE
#endif
  • Dans le cas d'un bibliothèque externe, un sous-espace de noms homonyme est utilisé (définir des macro pour simplifier) ; par exemple, pour Qwt, on obtient :
    namespace QExtend
    {
        namespace Qwt
        {
    
            /*...*/
        }
    }
    
  • Ne pas utiliser les exceptions : retournez des booléens ou proposez des fonctions getLastError().

Mots-clef interdits

  • Pour la compatibilité avec d'autre bibliothèques (comme boost), certain mots-clef de Qt sont formellement interdits, mais disposent d'un équivalent à utiliser :
    Interdit Équivalent
    signals Q_SIGNALS
    slots Q_SLOTS
    emit Q_EMIT
    foreach Q_FOREACH
    forever Q_FOREVER

Artistic Style

  • Pour remettre en forme votre code, il est possible d'utiliser artistic style
    La ligne de commande se rapprochant au plus des règles de codage :
    astyle --style=allman --indent=spaces=4 --indent-col1-comments --align-pointer=name --indent-switches --indent-preprocessor --break-blocks --pad-oper --pad-paren --pad-header --add-brackets --convert-tabs monfichier1.cpp monfichier1.h

6. Documentation

  • La documentation est généré par doxygen ;
  • La documentation d'un membre est à sa droite et contenue dans le commentaire
    /*!<... */
    ;
  • La documentation est situé au dessus de la classe ou de la fonction ;
  • La documentation d'une classe ou d'une fonctions est en deux partie :
 //!  correspond au tag \\brief. petite description 

 /*!    

    Reste de la documentation

*/
  • La documentation est en anglais et en français ;
  •  \~english  ouvre un block pour de la documention anglaise.
  •  \~french   ouvre un block pour de la documention française.
  •  \~   la documentation est partagée par toutes les langues.
#ifndef MONWIDGET_H
#define MONWIDGET_H

QE_BEGIN_NAMESPACE

//! \~english A test class
//! \~french Une classe de test

/*!

\~english
    A more elaborate class description.

\~french
    Description détaillée.

\~
   documentation partagé
*/
class MonWidget : public QWidget
{
    QSting  m_string;/*!<   \~english This is english.
                            \~french  En français*/

public :
    //! \~english A constructor
    //! \~french  Un constructeur
    /*!
        \author vy2
    \~english
        A more elaborate description of the constructor.

    \~french
        Desciption détaillé du constructeur.
    */
    MonWidget( );

 public Q_SLOTS:
    //!  \~english A slot
    //!  \~french Un slot
    /*!
    \~english
        A more elaborate description of the slot.

        \param  s   A string
        \return return a integer

    \~french
        Desciption détaillée du slot.

        \param  s   Une chaîne de caractères
        \return retourne un entier
    */
    int unSlot ( const QString & s);

Q_SIGNALS:

    //! A signal.
    /*!
        A more elaborate description of the signal.
    */
    void unSignal( const QString & s)

};

QE_END_NAMESPACE
#endif

Principaux tags

  • \param : paramètre d'une fonction ;
  • \tparam : paramètre template ;
  • \return : retour d'une fonction ;
  • \image : ajouter une image ;
  • \sa : créer des references vers des fonctions, classes....
  • On peut mettre du code HTML entre les tag \htmlonly ... \endhtmlonly ;
  • On peut mettre du code entre les tags \code ... \endcode.
  • Il est possible d'ajouter des diagrammes de séquence avec websequencediagrams
    \htmlonly   
    <div class=wsd wsd_style="modern-blue" style="text-align:center">
    <pre>
    participant "calculer nombre \npremier" as A
    participant "event loop" as E
    
    loop
    A->A: action
    A->E: run eventloop
    end
    </pre>
    </div>
    <script type="text/javascript" src="http://www.websequencediagrams.com/service.js"></script>
    
    \endhtmlonly
    

7. Autres fichiers

Ils ne seront pas encodés en UTF-8, mais bien en ANSI, pour la compatibilité avec QMake.

8. Conventions de nommage

Suivre ce que fait Qt, voir par exemple cet article : http://doc.trolltech.com/qq/qq13-apis.html