Table of Contents
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.
Estrutura geral dos arquivos .h
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.
License header
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. */
Para adicionar o License header a um conjunto de arquivos já existentes numa pasta, você pode usar o seguinte comando no Linux:
for i in `find . -name "*.js"`; do cp $i $i.bkp; cat ../header.txt $i.bkp > $i; rm -f $i.bkp; done
Apenas altere o *.js
para a extensão dos seus arquivos e crie o arquivo header.txt
na pasta abaixo, com o conteúdo descrito neste tópico. Para personalizar ainda mais o comando basta olhar o funcionamento do comando find
do shell. Por exemplo, você quer colocar o License header em todos os arquivos .h e .cpp de uma pasta, então você pode criar o header.txt
com o conteúdo correto (lembrar de deixar uma linha em branco no final) e executar o seguinte comando nesta pasta:
for i in `find . -name "*.h" -or -name "*.cpp"`; do cp $i $i.bkp; cat header.txt $i.bkp > $i; rm -f $i.bkp; done
File identification
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
*/
Header file guard
As convenções do File header guard estão descritas no documento de referência. A principal alteração é a troca do prefixo OGWS
por TERRAOGC
, segundo exemplo abaixo:
#ifndef __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H #define __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H
Includes section
A seção de includes deve seguir os seguintes princípios:
- Usar, sempre que possível, forward declarations
- Colocar primeiro os arquivos do mesmo pacotes (diretório fonte) através de aspas
- Colocar depois os arquivos de outros pacotes (outros diretórios) através de
<
e>
- 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>
Namespace declaration
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:
- Namespace sem forward declarations:
namespace TeOGC {
- Namespace com forward declarations:
// Forward declarations class TeTable; namespace TeOGC { // Forward declarations class TeWFSInsertElement; class TeWFSUpdateElement;
Classes and Functions declarations
Seguir o manual. Existem vários exemplos no próprio CVS.
End header file
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