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.

Comentários Iniciais

Todos os arquivos de código fonte devem começar apenas com o comentário “Copyright (c)”, exatamente conforme abaixo.

   /*
    * Copyright (c) 
    */

Obs.: O termo Copyright (c) é apenas para permitir a macro substituição no código quando for definido o Tipo de Licença e copyright do mesmo.