1. Padrão de codificação do QGIS

Esses padrões devem ser seguidos por todos os desenvolvedores do QGIS

1.1. Classes

1.1.1. Nomes

A classe em QGIS começa com Qgs e é formada usando camel case.

Exemplos:

  • QgsPoint

  • QgsMapCanvas

  • QgsRasterLayer

1.1.2. Membros

Os nomes dos membros da classe começam com um m minúsculo e são formados usando maiúsculas e minúsculas.

  • mMapCanvas

  • mCurrentExtent

Todos os membros da classe devem ser privados. Membros públicos na classe são FORTEMENTE desencorajados. Os membros protegidos devem ser evitados quando o membro pode precisar ser acessado a partir de subclasses Python, uma vez que os membros protegidos não podem ser usados ​​nas ligações Python.

Os nomes dos membros da classe estática mutável devem começar com s minúsculos, mas os nomes constantes dos membros da classe estática devem ser todos em maiúsculas:

  • sRefCounter

  • DEFAULT_QUEUE_SIZE

1.1.3. Funções do acessório

Os valores dos membros da classe devem ser obtidos através das funções do acessório. A função deve ser nomeada sem um prefixo de obtenção. As funções de acessório para os dois membros privados acima seriam.

  • mapCanvas()

  • currentExtent()

Certifique-se de que os acessadores estejam corretamente marcados com `` const``. Quando apropriado, isso pode exigir que as variáveis ​​de membro do tipo de valor em cache sejam marcadas com `` mutable``.

1.1.4. Funções

Os nomes das funções começam com uma letra minúscula e são formados usando maiúsculas e minúsculas. O nome da função deve transmitir algo sobre o propósito da função.

  • updateMapExtent()

  • setUserOptions()

Por consistência com a API QGIS existente e com a API Qt, abreviações devem ser evitadas. Por exemplo. SetDestinationSize ao invés de setDestSize, setMaximumValue ao invés de setMaxVal.

Os acrônimos também devem utilizar camel case para consistência. Por exemplo. SetXml ao invés de setXML.

1.1.5. Argumentos de função

Argumentos de função devem usar nomes descritivos. Não use argumentos de uma única letra (setColor( const QColor& color ) ao invés de setColor( const QColor& c )).

Preste muita atenção quando os argumentos devem ser passados por referência. A menos que os objetos dos argumentos sejam pequenos e copiados trivialmente (como objetos QPoint), eles devem ser passados ​​por referência. Por consistência com a API Qt, mesmo os objetos compartilhados implicitamente são passados ​​por referência (por exemplo, setTitle (const QString & title) ao invés de setTitle (QString title).

1.1.6. Valores de retorno da função

Retorna objetos pequenos e copiados trivialmente como valores. Objetos maiores devem ser retornados por referência const. A única exceção a isso são os objetos implicitamente compartilhados, que sempre são retornados por valor. Retorna QObject ou objetos de subclasse como ponteiros.

  • int maximumValue() const

  • const LayerSet& layers() const

  • QString title() const (QString é compartilhado implicitamente)

  • QList< QgsMapLayer* > layers() const (QList é compartilhado implicitamente)

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

  • QgsAbstractGeometry *geometry () const; (QgsAbstractGeometry é abstrato e provavelmente precisará ser moldado)

1.2. Documentação API

É necessário escrever a documentação API para cada classe, método, enumeração e outro código disponível na API pública.

O QGIS usa o Doxygen para documentação. Escreva comentários descritivos e significativos que forneçam ao leitor informações sobre o que esperar, o que acontece em casos extremos e dê dicas sobre outras interfaces que ele poderia estar procurando, práticas recomendadas e exemplos de código.

1.2.1. Métodos

As descrições dos métodos devem ser escritas de forma descritiva, usando a terceira pessoa. Os métodos requerem uma tag \since que define quando eles foram introduzidos. Você deve adicionar tags \since adicionais para alterações importantes que foram introduzidas posteriormente.

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

/**
 * \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. Classes Geradas

Classes QGIS geradas a partir dos arquivos Qt Designer (ui) devem ter o sufixo Base. Isto identifica a classe como uma classe base gerada.

Exemplos:

  • QgsPluginManagerBase

  • QgsUserOptionsBase

1.3.2. Diálogos

Todos os diálogos devem implementar dicas de contexto para todos os ícones da barra de ferramentas e outros widgets relevantes. Dicas de contexto auxiliam muito na descoberta de funcionalidade tanto para usuários novos quanto experientes.

Garanta que a ordem das tabulações para os widgets seja atualizada sempre que o layout de um diálogo for alterado.

1.4. Arquivos C++

1.4.1. Nomes

Arquivos C++ de código e cabeçalhos devem ter extensão .cpp e .h, respectivamente. Nomes de arquivos devem ser todos em minúsculas e, no caso de representar uma classe, ter o mesmo nome da classe.

Exemplo: os arquivos de origem da Classe QgsFeatureAttribute são qgsfeatureattribute.cpp e qgsfeatureattribute.h

Nota

No caso de não ter ficado claro na declaração acima, o nome do arquivo combinar com o nome da classe significa, implicitamente, que cada classe deve ser declarada e implementada em seu próprio arquivo. isto torna muito mais fácil para recèm-chegados identificar onde o código relativo para uma classe específica está localizado.

1.4.2. Cabeçalho Padrão e Licença

Cada arquivo de código fonte deve conter uma seção de cabeçalho padronizado conforme o exemplo a seguir:

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

Este é um template para o Qt Creator no git. Para usá-lo, faça uma cópia local de doc/qt_creator_license_template, ajuste o endereço de email e - se necessário - o nome e configure o QtCreator para usá-lo: Tools ► Options ► C++ ► File Naming.

1.5. Nomes de Variáveis

Nomes de variáveis locais devem começar com uma letra minúscula e serem formadas por maiúsculas e minúsculas. Não use prefixos como my ou the.

Exemplos:

  • mapCanvas

  • currentExtent

1.6. Tipos Enumerados

Tipos enumerados devem ser nomeados usando CamelCase iniciando com uma maiúscula. Exemplo:

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

Não use nomes de tipos genéricos que causarão conflito com outros tipos. Exemplo. Use UnknownUnit ao invés de Unknown

1.7. Constantes Globais & Macros

Constantes globais e macros devem ser escritas em maiúsculas e separadas por sublinha. ex.:

const long GEOCRS_ID = 3344;

1.8. Comentários

Comentários aos métodos de classe devem usar a terceira pessoa do indicativo ao invés do estilo imperativo:

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

1.9. Qt Signals e Slots

Todos as conexões de signal/slot devem ser feitas utilizando as conexões “new style” disponíveis no Qt5. Mais informações sobre este requisito está disponível em QEP #77.

Evite utilizar a auto conexão de slots do Qt (ex. aquelas nomeadas com void on_mSpinBox_valueChanged). Conexões automáticas são frágeis e tendem a se quebrar sem aviso se os diálogos são alterados.

1.10. Editando

Qualquer editor de texto/IDE pode ser utilizada para editar o código do QGIS desde que os seguintes requisitos sejam satisfeitos.

1.10.1. Tabulações

Ajuste seu editor para emular tabulações com espaços. As tabulações devem ser ajustadas para 2 espaços.

Nota

No vin isto é feito com set expandtab ts=2

1.10.2. Indentação

O código fonte deve ser recuado para melhorar a legibilidade. Existe um scripts/prepare-commit.sh que procura os arquivos alterados e os reutiliza usando astyle. Isso deve ser executado antes do commit. Você também pode usar scripts/astyle.sh para indentar arquivos individuais.

Como versões mais recentes de astyle recuam de forma diferente da versão usada para fazer uma reindentação completa da fonte, o script usa uma versão antiga de estilo, que incluímos em nosso repositório (ative WITH_ASTYLE no cmake para incluí-lo na compilação) .

1.10.3. Parênteses

Parênteses devem iniciar na linha seguindo a expressão:

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

1.11. Compatibilidade da API

Existe API documentation para C++.

Tentamos manter a API estável e com compatível com versões anteriores. Limpezas na API devem ser feitas de maneira similar ao código fonte Qt. 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. SIP Bindings

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

1.12.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 can be found in tests/code_layout/sipifyheader.h.

1.12.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 scripts/sip_include.sh needs to be executed.

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

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

1.12.3. Improving sipify script

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

1.13. Estilo de Codificação

Aqui são descritas algumas dicas de programação que, esperamos, reduzirão erros, tempo de desenvolvimento e manutenção.

1.13.1. Sempre que possível, generalize o código

Se fizer cópia-cola do código, ou escrevendo a mesma coisa mais de uma vez, considere consolidar o código em uma função.

Isso vai:

  • permitir que alterações sejam feitas em apenas um local ao invés de vários

  • ajuda a prevenir inchaço no código

  • tornar mais difícil para várias cópias irem se diferenciando longo do tempo, tornando mais difícil a compreensão e a manutenção para os outros

1.13.2. Prefira Ter Constantes Antes nos Predicados

Prefira colocar as constantes primeiro nso predicados.

0 == value ao invés de value == 0

Isso ajudará a impedir que os programadores acidentalmente usem `` = `` quando eles pretendem usar `` == ``, o que pode introduzir erros de lógica muito sutis. O compilador gerará um erro se você usar acidentalmente `` = `` em vez de `` == `` para comparações, uma vez que as constantes não podem ser atribuídas valores inerentes.

1.13.3. Espaços Podem Ser Seus Amigos

Adicionar espaços entre operadores, declarações e funções torna mais fácil para os humanos analisar o código.

O que é mais fácil de ler, isto:

if (!a&&b)

ou isto:

if ( ! a && b )

Nota

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

1.13.4. Coloque comandos em linhas separadas

Ao ler o código, é fácil perder os comandos, se não estiverem no início da linha. Ao ler rapidamente o código, é comum ignorar linhas se não se parecem com o que você procura nos primeiros caracteres. Também é comum esperar um comando após um condicional como `` if``.

Considere:

if (foo) bar();

baz(); bar();

É muito fácil perder parte do fluxo de controle. Em vez disso use

if (foo)
  bar();

baz();
bar();

1.13.5. Indente modificadores de acesso

Os modificadores de acesso estruturam uma classe em seções de API pública, API protegida e API privada. Os próprios modificadores de acesso agrupam o código nesta estrutura. Indente o modificador de acesso e as declarações.

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

1.13.6. Recomendações de Livros

Você também deve realmente ler este artigo do Qt Quarterly sobre designing Qt style (APIs)

1.14. Créditos para as contribuições

Colaboradores de novas funções são encorajados em deixar as pessoas saberem sobre suas contribuições por: