This is an old revision of the document!
Table of Contents
Padronização de Estilo de Programação em TerraLib
Padrões de Estilo para Programar em TerraLib
Padronização de Nomes
Padronização de Código
Padronização de Documentação DOxygen
Convenção de Programação
Resumo e Exemplos
Padronização de Nomes
1. Arquivo
1.1 Nome
- 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
1.2 Estrutura
<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:
- Definição da macro associada ao arquivo
- Definição de outras macros
- Inclusão de arquivos
- Includes de arquivos C
- Includes de arquivos locais
- Includes de arquivos de plataforma
- Includes de arquivos STL
- Declaração forward
- Namespace
- Inclusão de arquivos
- Usar
<…>
para externos e“…”
para locais - Usar path relativo
- Usar explicitamente os namespace externos. Ex: std::string
1.3 Comentário
- 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 (?)
*/
1.4 Exemplo
2. Macro
Nome
- Usar prefixo TE_
- Usar UPPERCASE e underscores (_) para separar palavras
- Para macros associadas a arquivos .h usar a extensão como sufixo _H
Comentário
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. */
Exemplo
#ifndef TE_CONNECTION_POOL_H #define TE_CONNECTION_POOL_H .... #define TE_MAX_FLOAT 3.4e37 .... #endif //end TE_CONNECTION_POOL_H
Namespace
Usar sempre o namespace TerraLib para todo o kernel.
Comentário
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. */
Exemplo
Classe e Estrutura
Nome
- 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.
Estrutura
- Os métodos e membros devem seguir a seguinte ordem:
- Métodos públicos
- Métodos protegidos
- Métodos privados
- Membros protegidos
- 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
Comentário
- 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
Classe e Estrutura
- 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 */
Método
- 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 */
Membro
- 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