Important

Traducerea este un efort al comunității, la care puteți să vă alăturați. În prezent, această pagină este tradusă 71.57%.

1. Standardele de codificare QGIS

QGIS coding standards are described in the policy document available at QEP #314. All developers are required to follow those policies. Please note that QEP #314 is a live document, and that these policies may change over time.

1.1. Clase

1.1.1. Funcțiile Accesor

Asigurați-vă că accesoriile sunt corect marcate cu const. Atunci când este cazul, este posibil ca variabilele membru, de tip cache de valoare, să fie marcate cu mutable.

1.1.2. Argumente ale funcțiilor

Acordați o atenție deosebită momentului când argumentele ar trebui să fie transmise prin referință. Cu excepția cazului în care obiectele argumentului nu au dimensiuni mari și sunt trivial de copiat (cum ar fi obiectele QPoint), ele ar trebui să fie transmise prin referințe constante. Pentru concordanța cu API-ul Qt, chiar și obiectele partajate în mod implicit sunt transmise prin referințe constante (ex.: setTitle( const QString& title ) în loc de setTitle( QString title ).

1.1.3. Valorile Returnate de Funcție

Returnați ca valori obiectele mici și trivial copiate. Obiectele mai mari ar trebui returnate prin referințe constante. Singura excepție o reprezintă obiectele partajate în mod implicit, care sunt întotdeauna returnate prin valoare. Returnați ca pointeri QObject sau obiectele subclasate.

  • int maximumValue() const

  • const LayerSet& layers() const

  • QString title() const (QString se partajează, în mod implicit)

  • QList< QgsMapLayer* > layers() const (QList se partajează, în mod implicit)

  • QgsVectorLayer *layer() const; (QgsVectorLayer moștenește pe QObject)

  • QgsAbstractGeometry *geometry() const; (QgsAbstractGeometry este abstract și, probabil, necesită specificarea tipului)

1.2. Documentația API

Este necesar să elaborați documentația API pentru fiecare clasă, metodă, enumerație și alt cod care este disponibil în API-ul public.

QGIS uses Doxygen for documentation. Write descriptive and meaningful comments that give a reader information about what to expect, what happens in edge cases and give hints about other interfaces he could be looking for, best practices and code samples.

1.2.1. Variabilele Membru

Variabilele membru ar trebui să se afle, în mod normal, în secțiunea private și să fie dispoibile prin intermediul funcțiilor get și set. O excepție o constituie containerele de date, cum ar fi raportarea erorilor. În astfel de cazuri, nu prefixați membrul cu un m.

1.3. Qt Designer

1.3.1. Clasele Generate

Clasele QGIS care sunt generate în fișierele produse de Qt Designer (UI) ar trebui să aibă sufixul Base. Acest lucru identifică o clasă de bază, generată.

Exemple:

  • QgsPluginManagerBase

  • QgsUserOptionsBase

1.3.2. Dialoguri

Toate dialogurile ar trebui să implementeze ajutorul pentru toate pictogramele barei de instrumente și alte controale grafice relevante. Baloanele cu indicii adaugă foarte mult la descoperirea caracteristicilor, atât pentru utilizatorii noi, cât și pentru cei experimentați.

Asigurați-vă că ordinea filelor pentru controalele grafice este actualizată ori de câte ori se modifică aspectul unui dialog.

1.4. Fișierele C++

1.4.1. Antetul Standard și Licența

Fiecare fișier sursă trebuie să conțină o secțiune antet, în conformitate cu exemplul următor:

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

Notă

There is a template for Qt Creator in git repository. To use it, copy it from qt_creator_license_template to a local location, adjust the mail address and - if required - the name and configure QtCreator to use it: Tools ► Options ► C++ ► File Naming.

1.5. Editarea

Orice editor de text/IDE poate fi folosit pentru a edita codul QGIS, oferind garanția că sunt îndeplinite următoarele cerințe.

1.5.1. Caracterele TAB

Setați în editorul dvs. emularea TAB-ului cu ajutotul spațiilor albe. Ar trebui folosite în acest scop 2 spații.

Notă

În vim, acest lucru se realizează prin comanda set expandtab ts=2

1.5.2. Indentarea

Source code should be indented to improve readability. There is a prepare_commit.sh file that looks up the changed files and reindents them using astyle. This should be run before committing. You can also use 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).

1.6. Compatibilitatea API-ului

Există Documentație API pentru C++.

We try to keep the API stable and backwards compatible. Cleanups to the API should be done in a manner similar to the Qt source code e.g.

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

Some of the SIP files are automatically generated using a dedicated script.

1.7.1. Pre-procesare antet

All the information to properly build the SIP file must be found in the C++ header file. Some macros are available for such definition:

  • Use #ifdef SIP_RUN to generate code only in SIP files or #ifndef SIP_RUN for C++ code only. #else statements are handled in both cases.

  • Use SIP_SKIP to discard a line

  • The following annotations are handled:

    • 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/

  • private sections are not displayed, except if you use a #ifdef SIP_RUN statement in this block.

  • SIP_PYDEFAULTVALUE(value) can be used to define an alternative default value of the python method. If the default value contains a comma ,, the value should be surrounded by single quotes '

  • SIP_PYTYPE(type) can be used to define an alternative type for an argument of the python method. If the type contains a comma ,, the type should be surrounded by single quotes '

A demo file, sipifyheader.h, is also available.

1.7.2. Generating the SIP file

The SIP file can be generated using a dedicated script. For instance:

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

To automatically generate the SIP file of a newly added C++ file sip_include.sh needs to be executed.

As soon as a SIP file is added to one of the source file (core_auto.sip, gui_auto.sip or analysis_auto.sip), it will be considered as generated automatically. A test on will ensure that this file is up to date with its corresponding header.

To force recreation of SIP files, sipify_all.sh shall be executed.

1.7.3. Improving sipify script

If some improvements are required for sipify script, please add the missing bits to the demo file sipifyheader.h and create the expected header sipifyheader.expected.sip file. This will also be automatically tested as a unit test of the script itself.

1.8. Setări

QGIS code base offers a mechanism to declare, register and use settings.

  • settings should be defined using one of the available implementations (QgsSettingsEntryString, QgsSettingsEntryInteger, …).

  • settings must be integrated in the settings tree (QgsSettingsTree), this is automatically done when using the constructor with a parent node (QgsSettingsTreeNode).

  • they are declared as const static either in a dedicated class or in the registry directly (core, gui, app, …).

  • the setting key should be using a kebab-case.

1.9. Stilul de Codificare

Aici sunt descrise câteva sugestii și sfaturi de programare care vor reduce, sperăm, erorile, timpul de întreținere și dezvoltare.

1.9.1. Generalizați Codul Atunci Când Este Posibil

Decât să duplicați un anumit cod, mai bine luați în considerare consolidarea acestuia într-o funcție unică.

Acest lucru vă va permite să:

  • efectuați modificări într-o singură locație în loc de mai multe

  • preveniți încurcarea codului

  • împiedica apariția, de-a lungul timpului, a diferențelor între secțiunile identice de cod, făcându-le, astfel, mai greu de înțeles și de întreținut de către alții

1.9.2. Puneți comenzile pe linii separate

La citirea codului, este ușor să omiteți comenzile dacă acestea nu se află la începutul liniei. La parcurgerea rapidă a codului, este normal să omiteți liniile atunci când acestea nu prezintă ceea ce căutați în primele câteva caractere. Este, de asemenea, normal să vă așteptați la o comandă după un condițional ca if.

Se ia în considerare următorul cod:

if (foo) bar();

baz(); bar();

Este foarte ușor să omiteți o parte din fluxul de control. Scrieți, în schimb

if (foo)
  bar();

baz();
bar();

1.9.3. Cărți recomandate

Ar trebui, de asemenea, să citiți acest articol de la Qt Quarterly despre proiectarea în stilul Qt (API)

1.10. Recunoașterea contribuțiilor

Contribuitorii la noile funcții sunt încurajați să-i informeze pe ceilalți despre contribuția lor prin: