Guidelines de Implementação

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) 
   {
       ...
   }

Estrutura

• A chave de abertura “{ “ de qualquer bloco (seja função, condicional, etc) deve estar na linha seguinte a declaração da sentença.
• A chave de fechamento deve ser o único caractere de uma linha e ser identada alinhando-se com a chave de abertura correspondente.

Identação

• Deve-se usar a auto identação de código que acompanha a maioria das IDE’s e editores. A identação deve ser feita com o caracter <TAB>.
• As sentenças dentro da sentença composta devem ser identadas com uma tabulação a mais.

Exemplos:

   void 
   some_function() 
   {
       int number_of_tables = 0; 
       int number_of_columns = 0;
       int number_of_lines = 0; 
   
       if(number_of_lines == 0)
       {
           number_of_columns = 1;
       }
   }

Largura das Linhas

Evite linhas com mais de 100 caracteres, pois elas não são bem apresentadas em alguns tipos de monitores e ferramentas.

Quebra de Linhas

Quando uma expressão não couber em uma única linha, quebrar a linha segundo os princípios gerais:

• Quebre depois de uma vírgula;
• Alinhe a nova linha ao início da expressão com o mesmo nível na linha anterior;
• Quebre depois de um operador;

Exemplos:

   //Função com grande número de parâmetros
   void 
   another_some_function(int too_long_expression_1, int too_long_expression_2, int too_long_expression_3,
                         int too_long_expression_4, int too_long_expression_5);
   { 
       the_variable = another_some_function_1(too_long_expression_1, 
                                              another_some_function_2(too_long_expression_2, 
                                                                      too_long_expression_3));
   }

   //Expressões Aritméticas:
   a_big_long_name_1 = a_big_long_name_2 * (a_big_long_name_3 + a_big_long_name_4 - a_big_long_name_5) +
                       4 * a_big_long_name_6; // FORMA DESEJÁVEL
   
   a_big_long_name_1 = a_big_long_name_2 * (a_big_long_name_3 + a_big_long_name_4 - 
                       a_big_long_name_5) + 4 * a_big_long_name_6; // EVITE

   //Senteça Condicional if:
   if ((boolean_expression_1 && boolean_expression_2) ||
       (boolean_expression_3 && boolean_expression_4) ||
      !(boolean_expression_5 && boolean_expression_6)) 
   {
       do_something();
   }

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.