"Let us change our traditional attitude to the construction of programs.
Instead of imagining that our main task is to instruct a computer what to do,
let us imagine that our main task is
to explain to human beings what we want a computer to do."
— Donald E. Knuth, Literate Programming

"First, beautiful software ought to be visually beautiful —
the written code I mean — and almost a pleasure to read."
— Don Sherwood Olson, escritor e ex engenheiro de software

"Any fool can write code that a computer can understand.
Good programmers write code that humans can understand."
— Martin Fowler, Refactoring: Improving the Design of Existing Code

Leiaute

Programas precisam ser entendidos não só por computadores, mas também (e principalmente) por seres humanos.  Nos exemplos abaixo, não tente entender o que o programa faz; preocupe-se apenas com o leiaute (= layout), ou seja, com a disposição do programa na folha de papel e na tela do monitor.  Observe, em especial,

• o recuo das linhas em relação à margem esquerda da página,
  também conhecido como indentação (= indentation) e
• os espaços que separam as palavras e símbolos.

A propósito, veja o verbete Programming Style na Wikipedia.

É fácil habituar-se a produzir um bom leiaute.  Com um pouco de prática, os dedos do programador, dançando sobre o teclado, passarão a fazer a coisa certa de maneira autônoma, deixando a mente do programador livre para cuidar de assuntos mais importantes.

Um bom leiaute

Eis uma amostra do melhor leiaute que conheço. Ele está de acordo (ou quase) com o leiaute sugerido por Making The Best Use of C no GNU Coding Standards.  (Veja também Elements of Programming Style, de Kernighan e Plauger, McGraw-Hill, 1978, 2a. edição.)

int func( int n, int v[])
{
   int i, j;
   i = 0;
   while (i < n) {
      if (v[i] != 0)
         i = i + 1;
      else {
         for (j = i + 1; j < n; ++j)  
            v[j-1] = v[j];
         n = n - 1;
      }
   }
   return n;
}

Veja como é fácil conferir o casamento de "{" com "}". Note como esse leiaute facilita as alterações do programa (remoção de linhas, inserção de novas linhas) em um editor de textos.

Tenha compaixão pelos seus leitores e não use fonte de espaçamento variável para escrever programas.  Veja como o resultado é inadequado:

int func( int n, int v[])
{
   int i, j;
   i = 0;
   while (i < n) {
     if (v[i] != 0) i = i + 1;
     else {
       for (j = i + 1; j < n; ++j)
         v[j-1] = v[j];
       n = n - 1;
     }
   }
   return n;
}

Um leiaute compacto

O leiaute abaixo ocupa menos espaço que o anterior. Ele é bom para escrever programas com lápis-e-papel (mas não tão bom para fazer alterações com o auxílio de um editor de textos). Indentação correta é essencial nesse leiaute.

int func( int n, int v[]) {
   int i, j;
   i = 0;
   while (i < n) {
      if (v[i] != 0)  i = i + 1;
      else {
         for (j = i + 1; j < n; ++j)  v[j-1] = v[j];
         n = n - 1; }}
   return n; }

Mau exemplo

O que você acha do leiaute no exemplo abaixo?

int func(  int n,int v[] ){
   int i,j;
   i=0;
   while(i<n){
      if(v[i] !=0) i=i +1;
      else
      {
         for(j=i+1;j<n;++j )  
            v[j-1]=v[j];
         n =n- 1;
      }
   }
   return n;
}

Este leiaute é péssimo.  Principalmente porque deixa espaços onde não deve e engole os espaços onde eles são necessários.  Os espaços no código são tão importantes quanto as pausas na música!

Infelizmente, alguns bons programadores e autores cometem esse tipo de atrocidade gratuita.  Espero que você não queira imitar esses maus exemplos.

Sugestões

Quer uma sugestão?  Use as mesmas regras tipográficas que todos os bons livros, revistas e jornais seguem:

• use um espaço para separar cada palavra da palavra seguinte
  (note que os símbolos  =,  <=,  while,  if,  for  etc.  contam como palavras);
• deixe um espaço depois, mas não antes, de cada sinal de pontuação;
• deixe um espaço depois, mas não antes, de fechar um parêntese;
• deixe um espaço antes, mas não depois, de abrir um parêntese.

A expressão  "while(j < n)"  tem o mesmo sabor que  "enquantoj for menor que n".  Portanto,

• jamais escreva   while(j < n)   no lugar de   while (j < n) ;
• jamais escreva   else{   no lugar de   else { ;
• evite escrever   for (i=1;i<n;++i)   no lugar de   for (i = 1; i < n; ++i) ;
• etc.

Há três exceções notórias a essas regras:  escreva  

• x->prox   e não   x -> prox ,
• x[i]   e não   x [i] ,
• x++   e não   x ++ .

Além disso, é usual não deixar espaços antes e depois dos operadores de multiplicação e divisão.  Assim, é aceitável escrever  x*y  em lugar de x * y  e  x/y  em vez de x / y.   Há mais uma exceção, ousada e controversa:  na definição e na invocação de uma função, podemos suprimir o espaço antes e inserir um espaço depois do abre-parêntese que introduz a lista de parâmetros ou argumentos.  Por exemplo:  func( 9, v) .   Mas isso não se aplica aos operadores while, for, if, return, sizeof etc., pois esses operadores não são funções.

Talvez você não goste dessas regras e queira adotar outras. De qualquer modo, seja consistente, isto é, faça as coisas sempre do mesmo jeito.

Exercícios

Dicas

• Há vários programas para produção automática de leiaute decente. Veja, por exemplo, o  indent  dos sistemas UNIX e GNU/Linux.
• Alguns editores de texto trocam, automaticamente, longas sequências de espaços pelo número apropriado de caracteres de tabulação (tabs). A substituição é imperceptível (pois caracteres de tabulação são invisíveis), mas tende a "estragar" o leiaute do programa impresso. Sugiro que você configure o seu editor de modo a desligar essa substituição automática.