Padronização de Estilo de Programação em TerraLib

Padrões de Estilo para Programar em TerraLib

Padronização de nomes de arquivos, classes, estruturas, métodos, etc.

Padrões de Estilo para Programar em TerraLib

• UpperCamelCase + prefixo Te
• Extensão .h e .cpp
• Mesmo nome da classe, estrutura ou namespace do seu conteúdo
• Para siglas usar todas as letras em maiúsculas

• <Enter> na última linha
• Máximo de 80 colunas por linha
• Uma classe ou estrutura por arquivo
• Toda a implentação deve estar no .cpp exceto as funções e métodos inline e que usam templates
• Identação com 2 espaços ao invés da tabulação
• Todo .h deve ter a macro associada ao arquivo
• Ordem no .h:
  1. Definição da macro associada ao arquivo
  2. Definição de outras macros
  3. Inclusão de arquivos
     1. Includes de arquivos C
     2. Includes de arquivos locais
     3. Includes de arquivos de plataforma
     4. Includes de arquivos STL
  4. Declaração forward
  5. Namespace
• Inclusão de arquivos
  • Usar <…> para externos e “…” para locais
  • Usar path relativo
• Usar explicitamente os namespace externos. Ex: std::string

• Todo .h terá um cabeçalho padrão contendo informações sobre licença, parceiros, etc.
• Os comentários para gerar a documentação DOxygen:
  • Devem seguir o estilo Qt (http://www.stack.nl/~dimitri/doxygen/docblocks.html) sem os *'s intermediários
  • Devem seguir o padrão abaixo e ter no mínimo as tags \file, \brief e \author:

/*! 
    \file   file name
    \brief  brief description about the file.
            Brief description continued.
 
     More detailed description.
 
    \author (?)
*/

Veja exemplo

• Usar prefixo TE_
• Usar UPPERCASE e underscores (_) para separar palavras
• Para macros associadas a arquivos .h usar a extensão como sufixo _H

O comentário para gerar a documentacao DOxygen deve seguir o padrão abaixo. A descrição breve é obrigatória e a descrição detalhada é opcional no caso de macros:

//!  A brief description. 
/*!
     A more elaborate description.
*/

#ifndef TE_CONNECTION_POOL_H
#define TE_CONNECTION_POOL_H
....
#define TE_MAX_FLOAT 3.4e37
....
#endif //end TE_CONNECTION_POOL_H

Veja exemplo completo

Usar sempre o namespace TerraLib para todo o kernel.

O comentário para gerar a documentacao DOxygen deve seguir o padrão abaixo. A descrição breve é obrigatória e a descrição detalhada é opcional no caso de namespace:

//!  A brief description. 
/*!
     A more elaborate description.
*/

Veja exemplo

• Nome
  • UpperCamelCase + prefixo Te
  • Usar substantivo
  • Usar o plural para nomes de coleções
  • Para siglas usar todas as letras em maiúsculas

• Nome dos membros
  • lowerCamelCase + sufixo “_”

• Nome dos métodos
  • lowerCamelCase
  • Usar sempre os prefixos “get” e “set” para acessar os membros. No caso de membro booleano, usar o prefixo “is” no método para acessá-lo.

• Os métodos e membros devem seguir a seguinte ordem:
  1. Métodos públicos
  2. Métodos protegidos
  3. Métodos privados
  4. Membros protegidos
  5. Membros públicos
• Usar explicitamente a palavra public
• No valor de retorno dos métodos usar sempre que possível const e referência
• Usar const nos métodos que não alteram o estado do objeto, ou seja, que não alteram os valores dos membros
• Nos parâmetros dos métodos usar sempre que possível const e referência
• Sempre usar nomes nos parâmetros
• Quando o método retorna uma estrutura, essa deve ser passada como parâmetro do método por referência. Nesse caso, o método não deve limpar essa estrutura antes de preenchê-la
• Usar “other” para nomes de parâmetros nos construtores de cópia e operadores de atribuição
• Usar os mesmos nomes dos membros nos métodos que os acessam diretamente

• Os comentários para gerar a documentação DOxygen:
  • Devem seguir o estilo Qt (http://www.stack.nl/~dimitri/doxygen/docblocks.html) sem os *'s intermediários

• No caso de classes e estruturas é obrigatório colocar as descrições breve e detalhada. A tag \sa é opcional:

//!  A brief description of class or struct. 
/*!
     A more elaborate description of class or struct.
     \sa     other definitions related to the class or struct  
*/

• Os métodos devem conter no mínimo uma descrição breve, a descrição de todos os seus parâmetros (tag \param) e do seu valor de retorno (tag \return). A descrição detalhada é opcional.

//!  A brief description. 
/*!
     A more elaborate description of class or struct.
     \param  name description
     \return description
*/

• A descrição do membro deve vir depois de sua definição.

int member01_;   //!< Brief description after the member
int member02_;   //!< Brief description after the member

Veja exemplo