Importante

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

1. Padrão de codificação do 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 do acessório

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.2. Argumentos de função

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 em uma constante. Por consistência com a API Qt, mesmo os objetos compartilhados implicitamente são passados ​​por referência em uma constante (por exemplo, setTitle (const QString & title) ao invés de setTitle (QString title).

1.1.3. 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 de API

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

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. Variáveis Internas

Variáveis ​​de membro normalmente devem estar na seção private e disponibilizadas via getters e setters. Uma exceção a isso é para contêineres de dados, como relatórios de erros. Nesses casos, não prefixe o membro com um m.

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

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/IDE pode ser utilizada para editar o código do QGIS desde que os seguintes requisitos sejam satisfeitos.

1.5.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 vim isto é feito com set expandtab ts=2

1.5.2. Indentação

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.

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.6. Compatibilidade da API

Existe API documentation para 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. Ligações SIP

Alguns dos arquivos SIP são gerados automaticamente usando um script dedicado.

1.7.1. Pré-processamento de cabeçalho

Todas as informações para construir corretamente o arquivo SIP devem ser encontradas no arquivo de cabeçalho C++. Algumas macros estão disponíveis para tal definição:

  • Use #ifdef SIP_RUN para gerar código apenas em arquivos SIP ou #ifndef SIP_RUN apenas para código C++. As instruções #else são tratadas em ambos os casos.

  • Use ``SIP_SKIP `` para descartar uma linha

  • As seguintes anotações são tratadas:

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

  • As seções private não são exibidas, exceto se você usar uma instrução #ifdef SIP_RUN neste bloco.

  • SIP_PYDEFAULTVALUE(value) pode ser usado para definir um valor padrão alternativo do método python. Se o valor padrão contém uma vírgula ,, o valor deve estar entre aspas simples '

  • SIP_PYTYPE(type) pode ser usado para definir um tipo alternativo para um argumento do método python. Se o tipo contém uma vírgula ,, o tipo deve estar entre aspas simples '

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

1.7.2. Gerando o arquivo SIP

O arquivo SIP pode ser gerado usando um script dedicado. Por exemplo:

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. Melhorando o script sipify

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. 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.9.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.9.2. 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.9.3. Recomendações de Livros

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

1.10. Créditos para as contribuições

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