Estándares de Codificación QGIS

Estos estándares deberían ser seguidos por todos los desarrolladores QGIS.

Clases

Nombres

Class in QGIS begin with Qgs and are formed using camel case.

Ejemplos:

  • QgsPoint
  • QgsMapCanvas
  • QgsRasterLayer

Miembros

Los nombres de los miembros de la clase comienzan con una minúscula m y se forman con mayúsculas y minúsculas.

  • mMapCanvas
  • mCurrentExtent

Todos los miembros de la clase deberían ser privados. Se desincentiva FUERTEMENTE miembros públicos de clase.

Funciones accesor

Los valores de los miembros de la clase deben obtenerse a través de funciones de acceso. La función debe ser nombrada sin un prefijo get. Las funciones de acceso para los dos miembros privados anteriores serían:

  • mapCanvas()
  • currentExtent()

Funciones

Function names begin with a lowercase letter and are formed using mixed case. The function name should convey something about the purpose of the function.

  • updateMapExtent()
  • setUserOptions()

Diseñador Qt

Clases Generadas

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

Ejemplos:

  • QgsPluginManagerBase
  • QgsUserOptionsBase

Diálogos

Todos los diálogos deberían implementar lo siguiente:

  • Tooltip help for all toolbar icons and other relevant widgets
  • ayuda WhatsThis para todos los widgets en el diálogo
  • Un botón opcional (aunque altamente recomendado) de Ayuda sensible al contexto
    eso dirije al usuario a la página de ayuda apropiada al iniciar su navegador web

Archivos C++

Nombres

C++ implementation and header files should have a .cpp and .h extension respectively. Filename should be all lowercase and, in the case of classes, match the class name.

Ejemplo: los archivos fuente de la clase QgsFeatureAttribute son qgsfeatureattribute.cpp y qgsfeatureattribute.h

Nota

In case it is not clear from the statement above, for a filename to match a class name it implicitly means that each class should be declared and implemented in its own file. This makes it much easier for newcomers to identify where the code is relating to specific class.

Encabezado y Licencia Estándar

Cada archivo fuente debería contener una sección de encabezado que siga el patrón del siguiente ejemplo:

/***************************************************************************
  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. To use it, copy it from doc/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.

Nombres de variables

Los nombres de variables comienzan con letra minúscula y se forman usan mezcla de minúscula y mayúscula.

Ejemplos:

  • mapCanvas
  • currentExtent

Tipos Enumerados

Enumerated types should be named in CamelCase with a leading capital e.g.:

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

Do not use generic type names that will conflict with other types. e.g. use UnkownUnit rather than Unknown

Constantes & Macros Globales

Constantes y macros globales deberían escribirse en mayúscula separada por guión bajo e.g.:

const long GEOCRS_ID = 3344;

Comments

Comments to class methods should use a third person indicative style instead of the imperative style:

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

Editado

Cualquier editor de texto/IDE puede ser usado para editar código QGIS, siempre que los siguientes requerimientos sean atendidos.

Tabulaciones

Defina su editor para emular tabulaciones con espacios. El espaciado de tabulación debería establecerse en 2 espacios.

Nota

En vim esto se hace con set expandtab ts=2

Indentación

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

Llaves

Llaves deberían iniciar la línea que sigue a la expresión:

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

Compatibilidad API

Existe Documentación API 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 sourcecode e.g.

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 Codificación

Aquí se describen algunas sugerencias y consejos de programación que esperamos que reduzcan errores, tiempo de desarrollo y mantenimiento.

Siempre que sea Posible Generalizar Código

Si usted está cortando y pegando código, o escribiendo la misma cosa más de una vez, considere consolidar el código en una sola función.

Esto hará:

  • permite que los cambios sean hechos en un lugar en vez de múltiples lugares
  • ayude a prevenir inflado de código
  • make it more difficult for multiple copies to evolve differences over time, thus making it harder to understand and maintain for others

Prefer Having Constants First in Predicates

Prefiera poner constantes primero en predicados.

0 == valor en vez de valor == 0

This will help prevent programmers from accidentally using = when they meant to use ==, which can introduce very subtle logic bugs.The compiler will generate an error if you accidentally use = instead of == for comparisons since constants inherently cannot be assigned values.

Espacioblanco Puede Ser Su Amigo

Adicionando espacios entre operadores, frases, y funciones hace más fácil que humanos analicen código.

Cula es más fácil de leer, esto:

if (!a&&b)

o este:

if ( ! a && b )

Nota

scripts/prepare-commit.sh se encargará de esto.

Ponga los comandos en líneas 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();

Indent access modifiers

Access modifiers structure a class into sections of public API, protected API and private API. Access modifiers themselves group the code into this structure. Indent the access modifier and declarations.

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

Recomendaciones de libros

Debería también leer este artículo de Qt Quarterly sobre designing Qt style (APIs)

Créditos para contribuciones

Se anima a los que contribuyen nuevas funciones a hacer conocer a la gente acerca de sus contribuciones mediante: