TWSG Code Conventions

O documento principal do TWSG Code Conventions pode ser encontrado no link (protegido). Este artigo no Wiki tende a ser um complemento deste manual de convenções de código.

Segundo o manual de convenções de código do TWSG, os arquivos de cabeçalho (.h) devem seguir esta estrutura:

Header_File
 |
 |--LICENSE_HEADER
 |
 |--FILE_IDENTIFICATION
 |
 |--HEADER_FILE_GUARD
 |
 |--INCLUDES_SECTION
 |
 |--NAMESPACE_DECLARATION
 |
 |--CLASSES_DECLARATION | FUNCTIONS_DECLARATION
 |
 |--END_HEADER_FILE

Estes componentes são discutidos brevemente nas subseções seguintes.

A licença atualmente adotada no TerraOGC é a GNU GPL v3. Portanto todos os arquivos de cabeçalho, e os de implementação também (.cpp) devem iniciar pelas seguintes linhas:

/*
  Copyright (C) 2007-2009 TerraLib Web Services Group.

  This file is part of TerraOGC - a framework for Web-GIS development.

  TerraOGC 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 3 of the License,
  or (at your option) any later version.

  TerraOGC Framework 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 General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with TerraOGC. See COPYING. If not, write to
  TerraLib Web Services Group at <twsg@dpi.inpe.br>
  or see the online site: http://www.dpi.inpe.br/twsg.
*/

Em seguida, todos os arquivos devem ser identificados com informações sobre seu nome, breve descrição e autor(es), segundo o exemplo abaixo:

/** \file TeCGIUtils.h
 *  \brief This file contains commom routines for dealing with CGI applications.
 *  \author Gilberto Ribeiro de Queiroz
 *  \author Emerson M A Xavier
 */

As convenções do File header guard estão descritas no documento de referência. A pŕincipal alteração é a troca do prefixo OGWS por TERRAOGC, segundo exemplo abaixo:

#ifndef  __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H
#define  __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H

A seção de includes deve seguir os seguintes princípios:

1. Usar, sempre que possível, forward declarations
2. Colocar primeiro os arquivos do mesmo pacotes (diretório fonte) através de aspas
3. Colocar depois os arquivos de outros pacotes (outros diretórios) através de < e >
4. Iniciar cada lista de pacotes (inclusive do atual) com um comentário

Exemplo:

// TerraOGC WFS Utils include files
#include "TeWFSUtilsConfig.h"
 
// TerraOGC GML include files
#include <gml/TeGMLQuerier.h>
 
// Shapelib include files
#include <shapefil.h>

Apenas inserir a declaração do namespace padrão do grupo. As forward declarations ocorrem antes e/ou depois desta declaração, dependendo do namespace ao qual as classes pertencem. Veja os exemplos:

1. Namespace sem forward declarations:

   namespace TeOGC
   {

2. Namespace com forward declarations:

   // Forward declarations
   class TeTable;
    
   namespace TeOGC
   {
       // Forward declarations
       class TeWFSInsertElement;
       class TeWFSUpdateElement;

Seguir o manual. Existem vários exemplos no próprio CVS.

Apenas um fecho para o arquivo. Contém o final das declarações do namespace e do file header guard. Exemplo:

}    // end namespace TeOGC
 
#endif  // __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H

Sempre lembrar de deixar uma linha em branco no final do arquivo

Documentar bem o código é essencial para o sucesso do projeto como um todo. Veja algumas dicas:

1. Para obter o efeito de negrito, você pode usar o comando \b antes da palavra que deseja destacar. Para mais de uma palavra use como em HTML. Exemplos:
   • \b must ⇒ must
   • <b>must use</b> ⇒ must use
2. Para destacar uma palavra em itálico use o comando \a. Para múltiplas palavras coloque entre as tags <i> e </i>. Exemplos:
   • \a loadInstances ⇒ loadInstances
   • <i>loadInstances method</i> ⇒ loadInstances method
3. Para um efeito de fonte monospace, use o comando \c. Para múltiplas palavras use as tags <tt></tt>. Exemplos:
   • \c sessionId ⇒ sessionID
   • <tt>sessionId parameter</tt> ⇒ sessionID parameter
4. Para usar uma lista sem numeração (como os exemplos acima), preceda cada termo com o comando \li. Exemplo:

\li OracleSpatial
\li PostgreSQL
\li PostGIS