Importante

A tradução é um esforço comunitário você pode contribuir. Esta página está atualmente traduzida em 42.16%.

1. Normas de Codificação 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. Classes

1.1.1. Funções de Acessor

Assegure-se que os acessores são corretamente marcados com const. Onde apropriado, isto poderá necessitar que as variáveis de membro tipo valor em cache são marcados com mutable.

1.1.2. Argumentos da função

Tenha atenção sempre que os argumentos sejam passados através de referência. A não ser que os argumentos sejam pequenos e copiados (tais como objetos QPoint), devem ser passados através da referência const. Por questões de consistência com o Qt API, mesmo os objetos implicitamente partilhados são passados através da referência const (por exemplo, setTitle( const QString& title ) em vez de setTitle( QString title ).

1.1.3. Valores de Retorno da Função

Devolva os objetos pequenos e trivialmente copiados como valores. Os objetos maiores devem ser devolvidos através da referência const. A única exceção a isto são os objetos implicitamente partilhados, que são sempre devolvidos por valor. Devolva objetos QObject ou atribuídos como subclasse como ponteiros.

  • int maximumValue() const

  • const LayerSet& layers() const

  • QString title() const (QString is implicitly shared)

  • QList< QgsMapLayer* > layers() const (QList is implicitly shared)

  • QgsVectorLayer *layer() const; (QgsVectorLayer inherits QObject)

  • QgsAbstractGeometry *geometry() const; (QgsAbstractGeometry is abstract and will probably need to be casted)

1.2. API Documentation

It is required to write API documentation for every class, method, enum and other code that is available in the public API.

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. Members Variables

Member variables should normally be in the private section and made available via getters and setters. One exception to this is for data containers like for error reporting. In such cases do not prefix the member with an m.

1.3. Qt Designer

1.3.1. Classes geradas

QGIS classes that are generated from Qt Designer (ui) files should have a Base suffix. This identifies the class as a generated base class.

Exemplos:

  • QgsPluginManagerBase

  • QgsUserOptionsBase

1.3.2. Diálogos

Todos os diálogos devem implementar dicas de ajuda para todos os ícones das barras de ferramentas e outros componentes relevantes. As dicas de ajuda são um grande auxílio para utilizadores novos ou experientes conhecerem as funcionalidades.

Certifique que a ordem das abas para os widgets é atualizada toda vez que a composição de uma janela mudar.

1.4. Ficheiros C++

1.4.1. Cabeçalho padrão e licença

Cada arquivo de código fonte deve conter um cabeçalho de acordo com o seguinte exemplo:

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

Nota

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

Qualquer editor de texto/ambiente de desenvolvimento (IDE) pode ser usado para editar códigos do QGIS, contanto que os seguintes requisitos sejam atendidos.

1.5.1. Separadores

Set your editor to emulate tabs with spaces. Tab spacing should be set to 2 spaces.

Nota

In vim this is done with set expandtab ts=2

1.5.2. Indentation

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. Compatibilidade da Interface de Programação da Aplicação

There is API documentation for 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. Header pre-processing

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. Configurações

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. Coding Style

Here are described some programming hints and tips that will hopefully reduce errors, development time and maintenance.

1.9.1. Where-ever Possible Generalize Code

If you are cut-n-pasting code, or otherwise writing the same thing more than once, consider consolidating the code into a single function.

Isto irá:

  • permitir que as alterações sejam feitas num só local em vez de em vários lugares

  • help prevent code bloat

  • make it more difficult for multiple copies to evolve differences over time, thus making it harder to understand and maintain for others

1.9.2. Colocar os comandos em linhas separadas

When reading code it’s easy to miss commands, if they are not at the beginning of the line. When quickly reading through code, it’s common to skip lines if they don’t look like what you are looking for in the first few characters. It’s also common to expect a command after a conditional like if.

Considere:

if (foo) bar();

baz(); bar();

It’s very easy to miss part of what the flow of control. Instead use

if (foo)
  bar();

baz();
bar();

1.9.3. Book recommendations

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

1.10. Créditos de contribuições

Os contribuidores de novas funções são encorajados a informar as pessoas sobre sua contribuição: