Mudanças entre as edições de "Guidelines de Implementação"
(→Funções e [http://pt.wikipedia.org/wiki/Método_(engenharia_de_software) Métodos]) |
(→Funções e [http://pt.wikipedia.org/wiki/Método_(engenharia_de_software) Métodos]) |
||
Linha 21: | Linha 21: | ||
*Devem ser em inglês; | *Devem ser em inglês; | ||
*Todas as letras devem ser minúsculas, sendo que as palavras são separadas por underscore (_); | *Todas as letras devem ser minúsculas, sendo que as palavras são separadas por underscore (_); | ||
− | *Para | + | *Para as funções ou métodos de atribuição e obtenção do valor de alguma variável, deve-se usar as palavras set e get, respectivamente, antes da palavra em inglês; |
− | *O nome | + | *O nome da função ou método tem que ser o mais claro possível, Não utilizar abreviações (ex: utilizar get_table_from_dictionary() ao invés de get_tb_f_dic() ); |
*Métodos são separados por duas (2) linhas em branco. | *Métodos são separados por duas (2) linhas em branco. | ||
*A declaração de uma função deve ser da seguinte forma: | *A declaração de uma função deve ser da seguinte forma: | ||
Linha 32: | Linha 32: | ||
<font color=#007A00>void</font> | <font color=#007A00>void</font> | ||
some_function() | some_function() | ||
+ | { | ||
+ | ... | ||
+ | } | ||
+ | |||
+ | |||
+ | <font color=#7A0000>int</font> | ||
+ | sum_integer(<font color=#7A0000>int</font> first_integer, <font color=#7A0000>int</font> second_integer) | ||
{ | { | ||
... | ... |
Edição das 15h57min de 19 de fevereiro de 2009
Introdução
Este documento estabelece o padrão de codificação de códigos-fonte para o projeto SCAE.
Regra Número 1
Quando você não puder encontrar uma orientação ou uma regra que se aplique ao seu caso; ou ainda, quando uma regra não se aplicar, ou mais obviamente, ou quando tudo falhar: use o senso comum e verifique os princípios fundamentais. Esta regra prevalece sobre todas as outras. O senso comum é necessário mesmo quando existem regras e orientações.
Variáveis
Os nomes das variáveis devem obedecer às seguintes regras:
- Todas as variáveis devem ser declaradas no início da função.
- Todas as letras devem ser minúsculas, sendo que as palavras são separadas por underscore (_);
- O nome da variável tem que ser o mais claro possível. Abreviações não devem ser utilizadas;
- Nomes de variáveis globais devem ser precedidas da letra “g” em minúsculo e undercore (ex: g_line_number ).
Constantes
Os nomes das constantes de classe devem ser todos em maiúsculas, com palavras separadas por underscore (“_”).Exemplo:
#define TABLE_WIDTH 90
Funções e Métodos
Os nomes das funções ou métodos devem obedecer às seguintes regras:
- Devem ser em inglês;
- Todas as letras devem ser minúsculas, sendo que as palavras são separadas por underscore (_);
- Para as funções ou métodos de atribuição e obtenção do valor de alguma variável, deve-se usar as palavras set e get, respectivamente, antes da palavra em inglês;
- O nome da função ou método tem que ser o mais claro possível, Não utilizar abreviações (ex: utilizar get_table_from_dictionary() ao invés de get_tb_f_dic() );
- Métodos são separados por duas (2) linhas em branco.
- A declaração de uma função deve ser da seguinte forma:
- primeira linha contém o tipo de retorno (ex: void)
- segunda linha o nome da função ou método e seus parâmetros
Exemplo:
void some_function() { ... } int sum_integer(int first_integer, int second_integer) { ... }
Comentários
Programas podem ter dois tipos de comentários: de implementação e de documentação. Comentários de implementação são aqueles encontrados em C++, delimitados por /*...*/ e //. Comentários de documentação ( “semelhantes à javadoc”) têm significado especial e são delimitados por /**...*/. Os comentários de documentação deverão ser aplicados somente às funções e métodos e serão processados pela ferramenta Doxygen. Esse tipo de comentário deverá seguir as seguintes regras:
- Apresentar uma descrição breve do método, sendo que o ponto (“.”) deve obrigatoriamente terminar a sentença.
- Se necessário, apresentar uma descrição mais detalhada após a descrição breve, que também deverá ser terminada com o ponto final (“.”)
- Descrever os parâmetros.
- Descrever qual será o retorno da função.
Exemplo:
/** * Descrição breve do método (obrigatoriamente tem que terminar com um ponto). * Caso seja necessário uma descrição mais detalhada essa deverá ser escrita * após a descrição breve .\ Se for preciso colocar um ponto no meio da descrição, * ele deverá preceder uma contra-barra seguida de espaço(“\ “) \. Após a * descrição detalhada encerrar com um ponto. * @param inss um float representando o inss * @param quantidade_anos inteiro representando a quantidade de anos * contribuídos * @return um float representando o valor total contribuído durante a quantidade * de anos informada */
Nota: informações sobre as tags podem ser obtidas em http://www.stack.nl/~dimitri/doxygen/commands.html
Comentários de implementação devem ser usados para :
- Desativar trechos de código
- Inserir informações a respeito da implementação particular. Neste caso:
- Eles devem complementar o código fonte, explicando o que não é óbvio.
- Eles devem ajudar o leitor a compreender a fundo os conceitos, as dependências e, sobretudo, a codificação de dados complexos ou algoritmos.
- Devem destacar: desvios de codificação ou padrões de design; o uso de features restritas e "truques" especiais.
Como regra geral, antes de inserir um comentário de implementação, responda à seguinte questão: Qual o valor que está sendo adicionado neste comentário?
Comentários de documentação devem descrever a especificação do código, de uma perspectiva independente da implementação e para ser lido por desenvolvedores que não necessariamente terão o código-fonte em mãos.
Dados de alteração de código devem ser comentados em Releases Liberadas do SCAE no momento em que as releases forem atualizadas no repositório.