Normas de Codificação QGIS

Estas normas deverão ser seguidas por todos os programadores do QGIS.

Classes

Nomes

As classes no QGIS começam com Qgs e cada palavra é iniciada com maiúsculas e unidas sem espaços.

Exemplos:

  • QgsPoint
  • QgsMapCanvas
  • QgsRasterLayer

Membros

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

  • mMapCanvas
  • mCurrentExtent

Todos membro das classe devem ser privadas. Desencorajamos o uso de membros de classes públicas

Funções de Acesso

Os valores dos membros da classe devem ser obtidos por meio de funções do acesso. A função deve ser nomeada sem um prefixo get. As funções de acesso para os dois membros particulares acima seriam:

  • mapCanvas()
  • currentExtent()

Funções

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

  • updateMapExtent()
  • setUserOptions()

Qt Designer

Classes Geradas

As classes QGIS geradas a partir dos ficheiros Qt Designer (ui) devem ter um sufixo Base. Isto identifica a classe como um classe base gerada.

Exemplos:

  • QgsPluginManagerBase
  • QgsUserOptionsBase

Caixa de Diálogos

Todas as caixas de diálogo devem ser implementados da seguinte forma:

  • A dica da ajuda para todos os ícones da barra de ferramentas e outros widgets relevantes
  • Ajuda O que é isto para todos os widgets na caixa de diálogo
  • Um botão opcional (altamente recomendado) com um contexto sensível
    isso redirecciona o utilizador para a página de ajuda apropriada correndo no seu navegador web

Ficheiros C++

Nomes

A implementação de C++ e os cabeçalhos dos ficheiros devem ter uma extensão .cpp e .h, respetivamente. O nome do ficheiro deve ser todo em minúsculas e, no caso das classes, corresponder ao nome da classe.

Exemplo: Classe QgsFeatureAttribute ficheiro de origem é qgsfeatureattribute.cpp e qgsfeatureattribute.h

Nota

No caso de não ficar claro na declaração acima, para um nome do ficheiro corresponder a um nome de classe, implicitamente significa que cada classe deve ser declarada e implementada no seu próprio ficheiro. Isso facilita muito para os recém-chegados identificarem onde o código está relacionado a uma classe específica.

Cabeçalho padrão e Licença

Cada ficheiro 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

Há um modelo para o Qt Creator no git. Para usa-lo, copie-no do ficheiro doc/qt_creator_license_template para uma pasta local, ajuste o endereço de e-mail e - caso necessário - o nome e configuração do QtCreator para usá-lo: ` Ferramentas` -> ``Opções` –> ``C++ ``–> Nome do Ficheiro`.

Nome das variáveis

Nomes de variáveis locais começam com minúscula e são formados com minúsculas e maiúsculas.

Exemplos:

  • mapCanvas
  • currentExtent

Tipos de Enumeração

Os tipos de enumeração devem ser iniciados com maiúsculas e unidas sem espaços, por exemplo:

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

Não use nomes de tipos genéricos que possam entrar em conflito com outros tipos. Ex.: usar UnkownUnit em vez de Unknown

Constantes Globais & Macros

Constantes globais e macros devem ser escritas em maiúsculas e underscore por exemplo.:

const long GEOCRS_ID = 3344;

Comentários

Comentários para métodos da classe devem usar um estilo indicativo da terceira pessoa em vez do estilo imperativo:

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

Editando

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

Tabulação

Defina o seu editor para simular a tabulação com espaços. O espaço da tabulação deve ser definido com 2 espaços.

Nota

No vim isso é feito com set expandtab ts=2

Identação

O código fonte deve ser indentado para melhorar a legibilidade. Existe um `` scripts / prepare-commit.sh`` que procura os ficheiros alterados e os re-indenta usando astyle. Isso deve ser executado antes de confirmar. Você também pode usar `` scripts / astyle.sh`` para indentar ficheiros individuais.

Como as versões mais novas da indentação astyle diferentemente da versão usada para fazer uma re-indentação completa da fonte, o script usa uma versão antiga do astyle, que incluímos no nosso repositório (permite que o WITH_ASTYLE no cmake o inclua na compilação).

Chaves

As chaves deve começar na linha a seguir à expressão:

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

Compatibilidade da Interface de Programação da Aplicação

Existe a Documentação API para C++.

Tentamos mante a API estável e com compatibilidade com versões anteriores. Limpeza da API deve ser feita de forma semelhante ao do código fonte do Qt.

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

Estilo de Programação

Aqui são descritos algumas truques e dicas de programação que esperemos que reduza os erros, tempo de desenvolvimento e manutenção.

Onde for Possível Generalize o Código

Se estiver a copiar e colar o código, ou gravar a mesma coisa mais de uma vez, considere consolidar o código numa única função.

Isto irá:

  • permitir que as alterações sejam feitas num só local em vez de em vários locais
  • ajuda previne erro no códgio
  • torna mais dificil para múltiplas cópias que envolvam diferenças ao longo do tempo, tornando mais dificil de entender e gerir por outros

Prefira ter Constantes Primeiro em Predicados

Prefira por constantes primeiro nos predicados.

0 == value em vez de value == 0

Isso ajudará a evitar que os programadores usem acidentalmente `` = `` quando tiverem que usar `` == ``, o que pode introduzir bugs lógicos muito subtis. O compilador irá gerar um erro se acidentalmente usar `` = `` em vez de `` == `` para comparações, já que a constantes não se pode atribuir valores inerentes.

O Espaço em branco Pode Ser Seu Amigo

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 tomarão conta disto.

Ponha os comandos em linhas separadas

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

Considere:

if (foo) bar();

baz(); bar();

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

if (foo)
  bar();

baz();
bar();

Modificadores de acesso indentados

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

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

Recomendações de leitura

Deverá também realmente ler este artigo do Qt Quarterly sobre Projetando o estilo Qt (APIs) <https://doc.qt.io/archives/qq/qq13-apis.html> _

Créditos de contribuições

Os colaboradores de novas funções são incentivados para informarem as pessoas sobre as suas contribuições: