1. Standards de développement QGIS

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

1.1. Classes

1.1.1. Noms

Les classes dans QGIS commencent par Qgs et sont nommées en utilisant le camel case.

Exemples:

  • QgsPoint

  • QgsMapCanvas

  • QgsRasterLayer

1.1.2. Membres

Les noms des membres de classe commencent par un m minuscule 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 publics. Les membres protégés doivent être évités pour que le membre soit accessible depuis des sous-classes Python, car les membres protégés ne peuvent pas être utilisés à partir des liaisons Python.

Les noms des membres mutables des classes statiques doivent commencer par un s minuscule, mais les noms des membres constants des classes statiques doivent être en majuscules :

  • sRefCounter

  • DEFAULT_QUEUE_SIZE

1.1.3. Fonctions d’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.

1.1.4. Fonctions

Les noms de fonction commencent par une minuscule et se composent de minuscules/majuscules. Le nom de fonction devrait évoquer 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 nommés en utilisant le camel case pour la cohérence. Par exemple, setXml au lieu de setXML.

1.1.5. Arguments de la fonction

Les noms des arguments de fonctions doivent être descriptifs. Ne pas utiliser de noms à une seule lettre (p. ex. setColor( const QColor& color ) plutôt que 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 (p. ex. setTitle( const QString& title ) au lieu de setTitle( QString title ).

1.1.6. Valeurs de retour de la fonction

Renvoie les objets petits et trivialement copiés en tant que valeurs. Les objets plus grands doivent être renvoyés par une référence const. La seule exception à cela est implicitement les objets partagés, qui sont toujours renvoyés par valeur. Renvoie « QObject » ou les objets sous-classes en tant que pointeurs.

  • int maximumValue() const

  • const LayerSet& layers() const

  • QString title() const (QString est implicitement partagée)

  • QList< QgsMapLayer* > layers() const (QList est implicitement partagé)

  • QgsVectorLayer *layer() const; (QgsVectorLayer hérite de QObject)

  • QgsAbstractGeometry *geometry() const; (QgsAbstractGeometry est abastrait et nécessitera probablement d’être typé)

1.2. Documentation de l’API

Il est requis d’écrire la documentation API pour chaque classe, méthode, enumération et autres codes disponible dans l’API publique.

QGIS utilise Doxygen pour la documentation. Rédigez des commentaires descriptifs et significatifs qui donnent au lecteur des informations sur ce à quoi il doit s’attendre, sur ce qui se passe dans les cas limites et lui donnent des indications sur d’autres interfaces qu’il pourrait rechercher, sur les meilleures pratiques et sur des échantillons de code.

1.2.1. Méthode

La description des méthodes doit être écrit sous forme descriptive en utilisant la 3ème personne. Les méthodes nécessitent le mot-clé since` qui définit quand elles ont été introduites.

/**
 * Cleans the laundry by using water and fast rotation.
 * It will use the provided \a detergent during the washing programme.
 *
 * \returns True if everything was successful. If false is returned, use
 * \link error() \endlink to get more information.
 *
 * \note Make sure to manually call dry() after this method.
 *
 * \since QGIS 3.0
 * \see dry()
 */

1.2.2. Variables membres

Les variables membres devraient normalement être dans la section private et rendues accessibles via les getters et les setters. Une exception à cela existe pour les conteneurs de données comme pour la remontée d’erreurs. Dans ces cas, ne préfixez pas les membres par un m.

/**
 * \ingroup core
 * Represents points on the way along the journey to a destination.
 *
 * \since QGIS 2.20
 */
class QgsWaypoint
{
  /**
   * Holds information about results of an operation on a QgsWaypoint.
   *
   * \since QGIS 3.0
   */
  struct OperationResult
  {
    QgsWaypoint::ResultCode resultCode; //!< Indicates if the operation completed successfully.
    QString message; //!< A human readable localized error message. Only set if the resultCode is not QgsWaypoint::Success.
    QVariant result; //!< The result of the operation. The content depends on the method that returned it. \since QGIS 3.2
  };
};

1.3. Qt Designer

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

1.3.2. 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 widgets 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 widgets est bien mis à jour à chaque fois que la boîte de dialogue de la couche change.

1.4. Fichiers C++

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

Exemple : Pour la classe QgsFeatureAttribute, les fichiers sources sont qgsfeatureattribute.cpp et 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.

1.4.2. 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++ ► Nommage de fichier.

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

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

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

1.8. Commentaires

Les commentaires des méthodes de classes devraient utiliser un style indicatif à la troisième personne plus qu’un style impératif:

/**
 * Creates a new QgsFeatureFilterModel, optionally specifying a \a parent.
 */
explicit QgsFeatureFilterModel( QObject *parent = nullptr );
~QgsFeatureFilterModel() override;

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

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

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

1.10.2. Indentation

Le code source doit être indenté pour améliorer la lisibilité. Le fichier scripts/prepare-commit.sh vérifie les fichiers modifiés et les ré-indente en utilisant l’utilitaire astyle. Il devrait être joué avant de commiter. Vous pouvez également utiliser le script scripts/astyle.sh pour indenter des fichiers individuellement.

Les nouvelles version de astyle indentent différemment que la version utilisée pour ré-indenter l’intégralité des sources, nous avons inclus une veille version du script astyle dans notre dépôt (activez la variable WITH_ASTYLE dans le cmake pour l’inclure dans votre build).

1.10.3. Accolades

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

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

1.11. Compatibilité API

Il y a: api: Documentation de l’API <> pour 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 use 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();
}

1.12. Liaisons SIP

Certain fichiers SIP sont automatiquement générés en utilisant un script dédié.

1.12.1. Pré-traitement d’en-tête

Toutes les informations pour construire proprement le fichier SIP doivent être présentes dans le fichier d’en-tête C++. Quelques macros sont disponibles pour ces définitions:

  • Utilisez #ifdef SIP_RUN pour générer du code uniquement dans les fichiers SIP ou #ifndef SIP_RUN pour le code C ++ uniquement. Les instructions #else sont gérées dans les deux cas.

  • Utilisez SIP_SKIP pour sauter une ligne

  • Les annotations suivante sont traitées:

    • SIP_FACTORY: /Factory/

    • SIP_OUT: /Out/

    • SIP_INOUT: /In,Out/

    • SIP_TRANSFER: /Transfer/

    • SIP_PYNAME(name): /PyName=name/

    • SIP_KEEPREFERENCE: /KeepReference/

    • SIP_TRANSFERTHIS: /TransferThis/

    • SIP_TRANSFERBACK: /TransferBack/

  • Les sections private ne sont pas affichées, sauf si vous utilisez une instruction #ifdef SIP_RUN dans ce bloc.

  • SIP_PYDEFAULTVALUE(valeur) peut être utilisé pour définir une valeur par défaut alternative à la méthode par python. Si la valeur par défaut contient une virgule « , », la valeur doit être entourée par des simples guillements  » “ « .

  • SIP_PYTYPE(type) peut-être utilisé pour définir une type alternatif d’un argument à la méthode par python. Si le type contient une virgule « , », le type doit être entouré de simples guillemets  » “ « .

Un fichier de démonstration peut être trouvé dans tests/code_layout/sipifyheader.h.

1.12.2. Générer le fichier SIP

Le fichier SIP peut être généré en utilisant un script dédié. Par exemple :

scripts/sipify.pl src/core/qgsvectorlayer.h > python/core/qgsvectorlayer.sip

Pour générer automatiquement le fichier SIP d’un fichier C++ nouvellement ajouté scripts/sip_include.sh doit être exécuté.

Dès qu’un fichier SIP est ajouté à l’un des fichiers source (: fichier: python / core / core.sip,: fichier:` python / gui / gui.sip` ou: file: python / analysis / analysis .sip), il sera considéré comme généré automatiquement. Un test sur Travis permettra de s’assurer que ce fichier est à jour avec son en-tête correspondant.

Pour forcer la recréation des fichiers SIP, scripts/sipify_all.sh doit être exécuté.

1.12.3. Améliorer le script sipify

Si certaines améliorations sont nécessaires pour le script sipify, veuillez ajouter les bits manquants au fichier de démonstration tests/code_layout/sipifyheader.h et créer l’en-tête attendu tests/code_layout/sipifyheader.expected.sip. Cela sera également testé automatiquement sur Travis en tant que test unitaire du script lui-même.

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

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

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

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

:file:scripts/prepare-commit.sh On s’occupera de ceci.

1.13.4. 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();

1.13.5. 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();
}

1.13.6. Recommandation de lecture

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

1.14. Crédits pour les contributions

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