This is an old revision of the document!
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. */
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 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
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
Dicas doxygen
Documentar bem o código é essencial para o sucesso do projeto como um todo. Uma boa referência para os comandos doxygen pode ser encontrada no link.
Veja algumas dicas:
- 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
- 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
- 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
- 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
fica:
- OracleSpatial
- PostgreSQL
- PostGIS