====== TWSG Code Conventions ======

O documento principal do TWSG Code Conventions pode ser encontrado no [[http://www.dpi.inpe.br/twsg/media/pub/restrito/code-conventions-2007-14-10-draft-pt-br.pdf|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: <code>
Header_File
 |
 |--LICENSE_HEADER
 |
 |--FILE_IDENTIFICATION
 |
 |--HEADER_FILE_GUARD
 |
 |--INCLUDES_SECTION
 |
 |--NAMESPACE_DECLARATION
 |
 |--CLASSES_DECLARATION | FUNCTIONS_DECLARATION
 |
 |--END_HEADER_FILE

</code>

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



==== License header ====

A licença atualmente adotada no TerraOGC é a [[http://www.gnu.org/licenses/licenses.html#GPL|GNU GPL v3]]. Portanto todos os arquivos de cabeçalho, e os de implementação também (.cpp) devem iniciar pelas seguintes linhas:
<code>
/*
  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.
*/
</code>

Para adicionar o //License header// a um conjunto de arquivos já existentes numa pasta, você pode usar o seguinte comando no Linux: <code bash>
for i in `find . -name "*.js"`; do cp $i $i.bkp; cat ../header.txt $i.bkp > $i; rm -f $i.bkp; done
</code>
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: <code bash>
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
</code>

==== 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:

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




==== 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:
<code cpp>
#ifndef  __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H
#define  __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H

</code>


==== 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:
<code cpp>
// TerraOGC WFS Utils include files
#include "TeWFSUtilsConfig.h"

// TerraOGC GML include files
#include <gml/TeGMLQuerier.h>

// Shapelib include files
#include <shapefil.h>

</code>

==== 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//: <code cpp>

namespace TeOGC
{

</code>
  - Namespace com //forward declarations//: <code cpp>
// Forward declarations
class TeTable;

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


</code>

==== 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:
<code cpp>
}    // end namespace TeOGC

#endif  // __TERRAOGC_COMMON_INTERNAL_TECGIUTILS_H


</code>
Sempre lembrar de deixar **uma linha em branco** no final do arquivo