Recomendações para Documentação e Desenvolvimento do V-ART

Versão 1.2

Bruno Schneider e Marta Villamil

Recomendações gerais

Tabulações:

Evite usar tabulações – configure seu editor de código para colocar espaços no lugar das tabulações, evitando assim que o código pareça sem identação em diferentes editores. O tamanho de cada tabulação é de 4 espaços.

Finais de Linha:

Não há padrão para o código de final de linha. Procure evitar que vários código se misturem no mesmo arquivo.

Conjunto de caracteres:

Não há padrão para o código de caracteres usado. Evite usar acentos ou outros caracteres especiais. Procure evitar que um arquivo use mais de um conjunto de caracteres.

Código HTML na documentação:

Deve ser evitado, para não conflitar com a definição externa do estilo da documentação.

Idioma

O idioma oficial da documentação do V-ART é o Inglês.

Tipos para parâmetros

Para facilitar a compreensão do código, deve-se seguir a seguinte convenção na declaração dos tipo de parâmetros:

1. Parâmetros de entrada: Se forem tipos básicos (como bool, int, double, etc.) podem ser passados por cópia (ex.: SetVisibility(bool newValue);). Caso contrário, devem ser passados por referência constante (ex.: SetPosition(const Point4D& newPosition);).
2. Parâmetros de saída ou de entrada e saída: Devem ser passados como ponteiros (ex.: GetPosition(Point4D* positionPtr);).

Nomes

Nomes de variáveis (variáveis locais e atributos de classe) devem começar com letra minúscula. Nomes compostos são escritos juntos, com maiúsculas separando as partes (ex.: vertexVector).

Nomes de classes devem começar com letra maiúscula. Nomes compostos são escritos juntos, com maiúsculas separando as partes.

Nomes de métodos e funções devem começar com letra maiúscula. Nomes compostos são escritos juntos, com maiúsculas separando as partes.

Documentação dos arquivos

A documentação de arquivos começa com \file, \brief e \version. Na versão, usar $Revision$ para que o CVS faça o controle automático do número da versão. Exemplo:

/// \file dof.cpp
/// \brief Implementation file for V-ART class "Dof".
/// \version $Revision: 1.8 $

Registro de alterações

Cada classe do framework tem um arquivo para armazenar o seu registro de alterações. Os registros devem conter data e nome da pessoa que realizou alerações, com uma descrição detalhado do que foi alterado. Exemplo:

Jun 04, 2004 – Bruno de Oliveira Schneider
- Alterei o método GetX()
- Acresentei o método GetZ()

O nome do arquivo com o registro de alterações é o nome da classe com a extensão .log. Exemplo: o registro de alterações da classe Dof fica no arquivo dof.h.

Documentação de Classes

A documentação de uma classe começa com um \class e um \brief.

Documentação das funções membro (métodos)

A documentação de funções membro devem obrigatoriamente estar no arquivo .h, pois é este arquivo (e não o .cpp) que estará disponível para os usuários da biblioteca V-ART. Recomenda-se que o arquivo .cpp também esteja comentado, mas não necessariamente fazendo uso do Doxygen.

A documentação de uma função membro deve começar com um \brief. O parâmetros, quando existirem e não forem triviais, devem ser comentados com \param. O valor que a função retorna, quando existir e não for trivial, deve ser documentado com \return.

Histórico de Alterações das Recomendações

07/JUN/2006 - 1.2 - Bruno Schneider

• Adicionei as seções Tipos para parametros e Nomes.
• Alterada a forma de fazer o registro de alterações.

05/JUN/2006 - 1.1 - Bruno Schneider

• Framework renomeado para V-ART.
• Alterada a forma de fazer o registro de alterações.

09/MAR/2006 - 1.0 - Bruno Schneider

• Alterada a forma de indicar a versão.
• Alterado o formato do Changelog.