"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 explaing to human beings what we want a computer to do."
— Donald E. Knuth, Literate Programming

"Programs must be written for people to read, and incidentally for machines to execute."
— H. Abelson, G. Sussman, The Structure and Interpretation of Computer Programs

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

Leiaute (= layout)

Programas devem 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 endentação (= indentation) e denteação,  e
• os espaços em branco que separam as palavras e símbolos.

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

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 com espaçamento variável para escrever programas.  Veja como o resultado é ruim:

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). Recuos corretos são essenciais 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; um verdadeiro "programa de índio". Principalmente porque deixa espaços em branco onde não deve e engole os espaços onde eles são importantes.

Infelizmente, alguns bons programadores e autores cometem esse tipo de atrocidade gratuita.  Espero que você não queira usar esses maus exemplos como licença para escrever mal.

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 em branco 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 de  "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 suprimir o espaço entre o nome de uma função e o abre-parêntese seguinte. Assim é usual escrever  func(9, v),  por exemplo.   Mas isso não se aplica aos operadores while, for, if, return, 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 seqüências de espaços em branco 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.