Outdated version of the documentation. Find the latest one here.

Standards de développement QGIS

Ces standards doivent être suivis par tous les développeurs de QGIS.

Classes

Noms

Une classe dans QGIS commence avec Qgs et est nommé en utilisant la casse camel.

Exemples:

  • QgsPoint
  • QgsMapCanvas
  • QgsRasterLayer

Membres

Les noms des membres de classe commencent par un minuscule m et sont composés de majuscules et de minuscules.

  • mMapCanvas
  • mCurrentExtent

Tous les membres d’une classe doivent être privés. Il est fortement déconseillé de déclarer des membres public. Les membres protégés doivent être évités pour que les membres soient accessibles depuis des sous-classes Python, alors que les membres protégés ne peuvent pas être utilisés à partir des liaisons Python.

Mutable static class member names should begin with a lower case s, but constant static class member names should be all caps:

  • sRefCounter
  • DEFAULT_QUEUE_SIZE

Accesseurs

Les valeurs des membres de la classe doivent être obtenues via les fonctions d’accesseur. La fonction doit être nommée sans préfixe “get”. Les fonctions d’accesseur pour les deux membres privés ci-dessus seraient:

  • mapCanvas()
  • currentExtent()

Assurez-vous que les accesseurs sont correctement marqués avec `` const``. Le cas échéant, cela peut nécessiter que les variables membres du type de valeur en cache soient marquées avec `` mutable``.

Fonctions

Les noms de fonction commencent par une minuscule et se composent de minuscules/majuscules. Il est recommandé de choisir un nom de fonction en rapport avec sa fonctionnalité.

  • updateMapExtent()
  • setUserOptions()

Par souci de cohérence avec l’API QGIS existante et avec l’API Qt, les abréviations doivent être évitées. Par exemple. “setDestinationSize” au lieu de “setDestSize”, “setMaximumValue” au lieu de “setMaxVal”.

Les acronymes devraient également être enveloppés de casse de chameau pour la cohérence. Par exemple. `` setXml`` au lieu de `` setXML``.

Arguments de la fonction

Function arguments should use descriptive names. Do not use single letter argments (e.g. setColor( const QColor& color ) instead of setColor( const QColor& c )).

Portez une attention particulière à quand les arguments devraient être passés par référence. À moins que les objets argument soient petits et trivialement copiés (tels que les objets QPoint), ils doivent être passés par une référence const. Par souci de cohérence avec l’API Qt, même les objets partagés implicitement sont passés par une référence const (par exemple `` setTitle (const QString & title) `` au lieu de `` setTitle (titre QString) ``.

Valeurs de retour de la fonction

Return small and trivially copied objects as values. Larger objects should be returned by const reference. The one exception to this is implicitly shared objects, which are always returned by value.

  • int maximumValue() const
  • const LayerSet& layers() const
  • QString title() const (QString is implicitly shared)
  • QList< QgsMapLayer* > layers() const (QList is implicitly shared)

Qt Designer

Les classes générées

Les classes QGIS générées depuis des fichiers Qt Designer (.ui) doivent avoir comme suffixe -Base. Cela permet d’identifier la classe comme étant une classe générée.

Exemples:

  • QgsPluginManagerBase
  • QgsUserOptionsBase

Dialogues

Toutes les boîtes de dialogue doivent intégrer des info-bulles d’aide pour toutes les icônes de la barre d’outils ainsi que pour les autres gadgets appropriés. Ces info-bulles apportent beaucoup à la découverte des fonctionnalités pour les utilisateurs débutants et confirmés.

Assurez-vous que l’ordre des onglets pour les gadgets est bien mis à jour à chaque fois que la boîte de dialogue de la couche change.

Fichiers C++

Noms

L’intégration du C++ et des fichiers en-têtes doivent respectivement avoir une extension en .cpp et en .h. Les fichiers doivent être nommés intégralement en minuscule et, dans le cas des classes, doivent correspondre avec le nom des classes.

Example: Class QgsFeatureAttribute source files are qgsfeatureattribute.cpp and qgsfeatureattribute.h

Note

Si le cas précédent n’est pas assez claire, pour qu’un nom de fichier corresponde au nom d’une classe, il est implicite que chaque classe soit déclarée et implémentée par son propre fichier. Cela permet aux nouveaux développeurs d’identifier plus rapidement le code lié à une classe donnée.

En-tête standard et licence

Chaque fichier source doit contenir une en-tête calquée sur l’exemple qui suit:

/***************************************************************************
  qgsfield.cpp - Describes a field in a layer or table
  --------------------------------------
  Date : 01-Jan-2004
  Copyright: (C) 2004 by Gary E.Sherman
  Email: sherman at mrcc.com
/***************************************************************************
 *
 * This program 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 2 of the License, or
 * (at your option) any later version.
 *
 ***************************************************************************/

Note

Il existe un modèle pour Qt Creator dans le dépôt Git. Pour l’utiliser, copiez-le depuis doc/qt_creator_license_template vers un emplacement local, adaptez l’adresse de courrier électronique et, si requis, le nom du développeur et configurez Qt Creator pour utiliser ce modèle: Outils -> Options -> C++ -> File Naming.

Noms de variable

Les noms des variables locales commencent par une minuscule et sont formés en utilisant des minuscules et majuscules. Ne pas utiliser de préfixes comme “my” ou “the”.

Exemples:

  • mapCanvas
  • currentExtent

Énumérations

Les énumérations doivent être nommés en CamelCase avec une première lettre en majuscule, ex:

enum UnitType
{
  Meters,
  Feet,
  Degrees,
  UnknownUnit
};

N’utilisez pas de noms génériques qui peuvent entrer en conflit avec d’autres types. Par exemple, utilisez UnkownUnit plutôt que Unknown

Constantes globales et Macros

Les constantes globales et les macros doivent être écrites en majuscules avec des séparateurs en tirets bas, ex:

const long GEOCRS_ID = 3344;

Signaux Qt et emplacements

Toutes les connections de signaux ou emplacements doivent être fait en utilisant les connections “new style” disponible en Qt5. De plus amples informations sur cette exigence sont disponibles dans “QEP #77 <https://github.com/qgis/QGIS-Enhancement-Proposals/issues/77>`_.

Évité d’utiliser l’emplacement de connexion automatique de Qt (c’est-à-dire ceux nommés `` void on_mSpinBox_valueChanged``). Les emplacement à connexion automatique sont fragiles et sujets à des ruptures sans avertissement si les boîtes de dialogue sont remaniées.

Edition

N’importe quel éditeur ou EDI peut être utilisé pour éditer le code de QGIS, sous réserve qu’il respecte les pré-requis suivants:

Tabulations

Paramétrez votre éditeur pour remplacer les tabulations par des espaces. L’espacement d’une tabulation doit être paramétrée pour occuper deux espaces.

Note

Sous Vim, vous pouvez utiliser set expandtab ts=2

Indentation

Source code should be indented to improve readability. There is a scripts/prepare-commit.sh that looks up the changed files and reindents them using astyle. This should be run before committing. You can also use scripts/astyle.sh to indent individual files.

As newer versions of astyle indent differently than the version used to do a complete reindentation of the source, the script uses an old astyle version, that we include in our repository (enable WITH_ASTYLE in cmake to include it in the build).

Accolades

Les accolades doivent commencer sur la ligne suivant l’expression:

if(foo == 1)
{
  // do stuff
  ...
}
else
{
  // do something else
  ...
}

Compatibilité API

There is API documentation for C++.

Nous essayons de conserver l’API stable et rétrocompatible. Les remises à niveau de l’API doivent être réalisées d’une manière similaire au code source de Qt, par ex.

class Foo
{
  public:
    /** This method will be deprecated, you are encouraged to use
     *  doSomethingBetter() rather.
     *  @deprecated doSomethingBetter()
     */
    Q_DECL_DEPRECATED bool doSomething();

    /** Does something a better way.
     *  @note added in 1.1
     */
    bool doSomethingBetter();

  signals:
    /** This signal will be deprecated, you are encouraged to
     *  connect to somethingHappenedBetter() rather.
     * @deprecated use somethingHappenedBetter()
     */
#ifndef Q_MOC_RUN
    Q_DECL_DEPRECATED
#endif
    bool somethingHappened();

    /** Something happened
     *  @note added in 1.1
     */
    bool somethingHappenedBetter();
}

Style de code

Voici quelques trucs et astuces de programmation qui, nous l’espérons, vous aideront à réduire les erreurs, le temps de développement et la maintenance.

Lorsque c’est possible, utiliser du code générique

Si vous copiez-collez du code, ou si vous écrivez la même chose plusieurs fois, pensez à consolider le code en une seule fonction.

Cela permettra:

  • Autorisez les changements à s’effectuer à un seul endroit plutôt qu’en de multiples emplacements.

  • de prévenir le code pourri

  • de rendre plus difficile l’évolution différenciée de plusieurs copies au fil du temps, phénomène qui rend plus difficile la compréhension et la maintenance pour les autres développeurs

Placez les constantes en premier dans les expressions

Placez les constantes en premier dans les expressions

0 == value à la place de value == 0

Cela empêchera les développeurs d’utiliser accidentellement = au lieu de ==, ce qui peut introduire des bogues logiques et subtils. Le compilateur générera une erreur si vous utilisez accidentellement = à la place de == pour les comparaisons puisque les constantes ne peuvent pas se voir assigner des valeurs.

Le caractère espace peut être votre ami

Ajouter des espaces entre les opérateurs, les instructions et les fonctions rendent le code plus lisible.

Ce qui est plus facile à lire, ceci:

if (!a&&b)

ou ceci:

if ( ! a && b )

Note

scripts/prepare-commit.sh will take care of this.

Placer les commandes sur des lignes séparées

Lors de la lecture du code il est facile de rater des commandes, si elles ne sont pas en début de ligne. Lors d’une lecture rapide, il est courant de sauter des lignes si elles ne semblent pas correspondre avec ce que l’on cherche dans les premiers caractères. Il est aussi commun de s’attendre à une commande après un conditionnel comme if.

Considérez ceci:

if (foo) bar();

baz(); bar();

Il est très facile de rater des extraits dans le flux de contrôle. Au lieu de cela, utiliser

if (foo)
  bar();

baz();
bar();

Indenter les modificateurs d’accès

Les modificateurs d’accès structurent une classe en sections publique, protégée et privée de l’API. Les modificateurs d’accès eux-mêmes groupent le code dans cette structure. Indentez les modificateurs d’accès et les déclarations.

class QgsStructure
{
  public:
    /**
     * Constructor
     */
     explicit QgsStructure();
}

Recommandation de lecture

You should also really read this article from Qt Quarterly on designing Qt style (APIs)

Crédits pour les contributions

Les contributeurs aux nouvelles fonctionnalités sont encouragés à faire connaître aux gens leur contribution via: