3.6. Comentários, indentação e outros promotores da legibilidade

Ao longo destas páginas vamos estar preocupados com a questão da legibilidade que é, entre outras, uma propriedade muito importante dos programas, pois facilita muito a sua manutenção (correção de erros, alteração, etc), não só por quem os escreveu como por qualquer outro programador.

Quando escrevemos um programa, há variadíssimas opções que podemos tomar que promovem a legibilidade. Vamos ver aqui algumas técnicas simples.

3.6.1. Comentários

O compilador de Java permite-nos escrever texto nos programas que não é interpretado como instruções – os comentários.

Para um programador, os comentários servem para ajudar à compreensão das várias partes do programa, sejam elas o significado das variáveis, a explicação de alguma expressão mais complexa, etc.

• Podemos inserir comentários de linha – texto que se situa entre os carateres // e o fim da linha onde se encontram.

  xxxxxxxxxx
  double raiz = Math.sqrt(17.0 * i);            // raiz quadrada de 51
  ​
  System.out.println( Math.sin(raiz));          // seno de um valor em radianos
  ​
  // o triplo do valor arredondado do logaritmo na base 10 do valor de raiz
  int k = 3 * Math.round(Math.log10(raiz)));
  

   

• Podemos inserir comentários de bloco – texto que se situa entre /* e */.

  xxxxxxxxxx
  double raiz = Math.sqrt(17.0 * i);            /* raiz quadrada de 51 */
  ​
  /*
    o triplo do valor arredondado do logaritmo na base 10
    do valor da variavel raiz
   */
  int k = 3 * Math.round(Math.log10(raiz)));
  

• Podemos inserir comentários de documentação Javadoc – texto que se situa entre /** e */.

  • Estes são comentários a serem reconhecidos por uma aplicação que os usa para gerar documentação em formato html (mais sobre isto no próximo capítulo).

3.6.2. Espaços

Para o compilador Java, os espaços a mais são ignorados, o que nos permite usá-los para melhorar a legibilidade dos programas.

Devemos, por exemplo, utilizar um espaço antes e após qualquer operador binário (exceto o ponto).

Preferimos

xxxxxxxxxx
System.out.println(4 * (245 + 455) * (17 + 3));
int expr3 = 5 + j – i / 4;
double raiz = Math.sqrt(17.0 * i);

a

xxxxxxxxxx
System.out.println(4*(245+455)*(17+3));
int expr3=5+j–i/4;
double raiz=Math.sqrt(17.0*i);

Usamos também linhas em branco para separar partes do nosso programa. Gostamos disto:

xxxxxxxxxx
public class Expressions3 {
​
    public static void main (String [] args) {
    
       int i;
       i = 2;
       int j = 6;
       double d1 = 3.5;
       double d2 = 10;
    
       int expr1 = 5 + j – i / 4;
       int expr2 = 5 + (j – i) / 4;
       int expr3 = (5 + (j – i)) / 4;
    
    }
}

Linhas demasiado longas podem parecer bem no terminal, mas não quando impressas. Vamos limitar-nos a 80 carateres por linha, partindo linhas demasiado longas.

Ao longo deste livro veremos outros casos em que devemos usar espaços.

3.6.3. Indentação

A indentação é uma forma de usar os espaços em branco que é fundamental para a legibilidade dos programas. Uma classe Java define um bloco entre chavetas. Um método Java também define um bloco entre chavetas. Como iremos ver nos próximos capítulos, as instruções do programa também definem blocos.

A ideia é indentar – “empurrar” para a direita, usando espaços – todas as linhas de um programa que constituam um novo bloco.

Preferimos:

xxxxxxxxxx
public class Expressions1 {
    public static void main (String [] args) {
        System.out.println(245 + 455);
    }
}

a

xxxxxxxxxx
public class Expressions1 {
public static void main (String [] args) {
System.out.println(245 + 455);}
}

e a

xxxxxxxxxx
public class Expressions1{public static void main(String [] args) {System.out.println(245+455);}}

Anterior: 3.5. Ainda as expressões

Seguinte: 4. Abstração procedimental