Padrão de codificação do QGIS¶

Nomes¶

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

Exemplos:

• QgsPoint
• QgsMapCanvas
• QgsRasterLayer

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.

Mutable static class member names should begin with a lower case s, but constant static class member names should be all caps:

• sRefCounter
• DEFAULT_QUEUE_SIZE

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

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.

Argumentos de função¶

Function arguments should use descriptive names. Do not use single letter argments (e.g. setColor( const QColor& color ) instead of 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).

Valores de retorno da função¶

Return small and trivially copied objects as values. Larger objects should be returned by const reference. The one exception to this is implicitly shared objects, which are always returned by value.

• int maximumValue() const
• const LayerSet& layers() const
• QString title() const (QString is implicitly shared)
• QList< QgsMapLayer* > layers() const (QList is implicitly shared)

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

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.

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.

Example: Class QgsFeatureAttribute source files are qgsfeatureattribute.cpp and qgsfeatureattribute.h

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

Tabulações¶

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

Indentação¶

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

Parênteses¶

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

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

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

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.

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 )

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

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

Recomendações de Livros¶

• Effective Modern C++, Scott Meyers
• More Effective C++, Scott Meyers
• Effective STL, Scott Meyers
• Design Patterns, GoF

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