TerraMA² - Convenções de Codificação

Autor: Gilberto Ribeiro de Queiroz
Data: 14/06/2015

Resumo: Este documento apresenta as convenções de estilo de codificação utilizadas no projeto TerraMA².

Introdução

A palavra estilo (style) no contexto deste documento possui uma conotação mais ampla do que apenas formatação de código fonte. Aqui serão apresentadas convenções que definirão alguns idiomas e padrões para reforçar a consistência do repositório, facilitando a legibilidade do código, bem como evitando alguns erros comuns de programação em C++.

Sumário

TODO: montar uma tabela como uma espécie de sumário por tópicos!

C++11

Dê preferencia ao uso de bibliotecas e extensões da linguagem C++11, que em alguns compiladores (GCC 4.7 ou anteriores) era conhecida por C++0x.

No entanto, antes de utilizar os recursos de C++11, considere possíveis questões de portabilidade para outros ambientes e plataformas.

Os seguintes recursos de C++11 devem ser evitados:

• Apenas funções lambda devem utilizar o construtor auto para omitir o tipo de retorno. Por exemplo, uma função livre como: auto foo() { ... } deve ser escrita como: int foo() { ... } .
• Os arquivos de cabeçalho <cfenv> e <fenv.h> possuem alguns idiossincrasias.

Convenções de Formatação e Nomenclatura

• Utilize dois espaços para recuar o texto (indentação).
• Nunca utilize tabs. Configure seu editor para substituir tabs por espaços.
• Nunca utilize caracteres especiais ou letras acentuadas.
• Coloque as chaves delimitadoras de bloco em linhas separadas e alinhadas:

  Point::Point(double x, double y, uint32 srid)
  {
    if (srid == 0)
    {
      ...
    }
  }
  

• Recue os comandos após um rótulo (label):

  void Foo(int n)
  {
    loop:
  
      for(int i = 0; i != n; ++i)
      {
        ...
      }
  }
  

Arquivos de Cabeçalho (Header Files)

Em geral, todo arquivo com a extensão .cpp deve ter um arquivo com a extensão .hpp associado. As exceções são os arquivos de testes unitários, de exemplos ou que possuam apenas uma função main().

Procure utilizar um arquivo de cabeçalho por definição de classe. Neste caso dê ao nome do arquivo o mesmo nome da classe sendo definida, adicionando-se a extensão .hpp. Exemplo: a classe Stack será definida em um arquivo denominado Stack.hpp.

Arquivo: Stack.hpp

class Stack
{
  public:

    ...
};

Hierarquias de classes ou estruturas relacionadas, cuja definição seja muito concisa, podem ser definidas no mesmo arquivo de cabeçalho. Neste caso, procure nomear o arquivo a partir da abstração sendo modelada. Exemplo: a hierarquia de exceções pode ser agrupada em um arquivo denominado Exception.hpp.

Arquivo: Exception.hpp

struct Exception: virtual std::exception, virtual boost::exception { };

struct SlotConnectionError: virtual Exception { };

struct SingletonViolationError: virtual Exception { };

...

Um conjunto de funções relacionadas podem ser agrupadas por arquivo de cabeçalho. Exemplo: um conjunto de funções para operações em strings pode ser declarado no arquivo StringUtils.hpp.

Arquivo: StringUtils?.hpp

std::vector<std::string> Tokenizer(const std::string& tokens);

std::string ToUpper(const std::string& value);

...

Macros de Guarda

Todo arquivo de cabeçalho deve ter uma macro de guarda para previnir múltiplas inclusões. Esta macro deve respeitar a seguinte forma geral: __TERRAMA2_INTERNAL_<PATH>_<FILE>_HPP__.

Este formato é baseado no prefixo TERRAMA2_INTERNAL_, mais o caminho completo do arquivo, seguido do sufixo _HPP. Este formato garantirá que as macros não se repitam.

Por exemplo, o arquivo Version.hpp contido no caminho terrama2/core/Version.hpp terá a seguinte macro de guarda:

#ifndef __TERRAMA2_INTERNAL_CORE_VERSION_HPP__
#define __TERRAMA2_INTERNAL_CORE_VERSION_HPP__

// STL
#include <string>

...

#endif // __TERRAMA2_INTERNAL_CORE_VERSION_HPP__

Cabeçalhos dos Arquivos

O cabeçalho para todos os arquivos do projeto TerraMA2 é descrito abaixo:

/*
  Copyright (C) 2007 National Institute For Space Research (INPE) - Brazil.

  This file is part of TerraMA2 - a free and open source computational
  platform for analysis, monitoring, and alert of geo-environmental extremes.

  TerraMA2 is free software: you can redistribute it and/or modify
  it under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation, either version 3 of the License,
  or (at your option) any later version.

  TerraMA2 is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with TerraMA2. See LICENSE. If not, write to
  TerraMA2 Team at <terrama2-team@dpi.inpe.br>.
*/

/*!
  \file terrama2/gui/admin/Example.cpp

  \brief Brief description of the file.

  \author AuthorName
*/

Nomenclatura de Funções

Nomenclatura de Classes

  void hello()
  {
      return "world";
  }

Nomenclatura de Arquivos e Diretórios

Todo código fonte, com excessão do "main.cpp", devem estar nomeados com a primeira letra maiúscula.

mainDialog.cpp => MainDialog.cpp

Os formulários com extensão (*.ui) das interfaces gráficas do TerraMA2 estão nas respectivas pastas:

src/terrama2/gui/admin/ui
src/terrama2/gui/config/ui

Caso haja a necessidade de compartilhar componentes entre as interfaces gráficas, adicionar na pasta "core":

src/terrama2/gui/core/ui

A nomenclatura para os formulários do TerraMA2 é apresentado abaixo:

Janela de diálogo => PluginManagerDialogForm.ui

Os arquivos com extensão ".hpp" e ".cpp" que irão compor os formulários, deverão ter o seguinte padrão:

PluginManagerDialog.hpp
PluginManagerDialog.cpp

Nomenclatura de Ícones e Diretórios

Os ícones estão presentes na pasta share/icons/terrama2/ e são apresentados da seguinte forma:

share/icons/terrama2/16x16 => ícones de 16 x 16
share/icons/terrama2/32x32 => ícones de 32 x 32
...
share/icons/terrama2/scalable => ícones no formato SVG

Para uma melhor organização, foram criadas subpastas: "admin", "config" e "generic". Em admin, colocar todos os ícones relativos ao módulo de administração. Em config, colocar todos os ícones relativos ao módulo de configuração. Em generic, colocar todos os ícones relativos a todos os módulos.

confirm.png (16x16) => "share/icons/terrama2/16x16/generic";
add-additional-data-vector.png (16x16) => "share/icons/terrama2/16x16/config";
administration.ico (48x48) => "share/icons/terrama2/48x48/admin/administration.ico".

Os ícones são mapeados em um arquivo "index.theme". Este arquivo corresponde a um conjunto de ícones disposta em uma estrutura de diretórios que compartilham uma aparência comum. O arquivo "index.theme" do TerraMA2 está presente em "share/icons/terrama2/index.theme"

[icon Theme]
Name=TerraMA2
Name[pt]=TerraMA2
Comment=icon Library for TerraMA2
Comment[pt]=Biblioteca de ícones do TerraMA2
Directories=16x16/config,16x16/generic,24x24/config,24x24/generic,32x32/config,32x32/generic,48x48/config,48x48/generic,
64x64/config,64x64/generic,128x128/config,128x128/generic,scalable,layout
Inherits=tango

[16x16/admin]
Size=16
Type=Fixed
Context=Applications

[16x16/config]
Size=16
Type=Fixed
Context=Applications

[16x16/generic]
Size=16
Type=Fixed
Context=Applications

...

Nomes de Funções Membro

Nomes de Membros de Dados

Namespaces

Referências Bibliográficas

IDE

Em anexo o arquivo de configuração do QtCreator? com a formatação do código no padrão TerraMA2