O que e' "clareza do codigo"

[Nelson Posse Lago <lago@that.com.br>]

Ola',

Um aluno me escreveu perguntando sobre "clareza do codigo". Vou reproduzir
aqui trechos da resposta que enviei a ele:

"Clareza do codigo" se refere basicamente `a clareza no estilo de
programacao, ou seja: evitar variaveis globais, definir funcoes de tamanho
relativamente pequeno que realizem uma tarefa bem definida, dividir o
programa em modulos de diferentes funcionalidades e estabelecer interfaces
claras e consistentes entre esses modulos, escolher nomes significativos
para variaveis e funcoes etc.  Basicamente, a ideia e' que se eu olhar
duas ou tres funcoes que compoem um modulo do seu programa, eu vou ter uma
ideia razoavel sobre o funcionamento dessas funcoes, sem precisar ler e
entender o programa inteiro nem gastar horas tentando entender uma funcao
extremamente longa ou complexa.

Se voce, por exemplo, resolver processar os argumentos da linha de comando
dentro de um "loop", o ideal e' que, para cada "coisa" que voce detecta na
linha de comando, seja executado um numero bem pequeno de acoes. Desse
jeito, o "loop" que trata a linha de comando fica bem mais facil de ler.
Vejamos (sem tratamento de erros):

void usage () {
	printf ("O programa...");
}

for (i = 1; i < argc; i++) {
	if (strcmp (argv[i], "-f") == 0) {
		frequencia = atoi (argv[i+1]);
	} else if (strcmp (argv[i], "-n") == 0) {
		num_asteroides = atoi (argv[i+1]);
	} else if (strcmp (argv[i], "-s") == 0) {
		seed = atoi (argv[i+1]);
	} else if (strcmp (argv[i], "-?" == 0) || \
		   strcmp (argv[i], "--ajuda") == 0) {
		usage ();
	}
}

Quando voce olha esse loop, voce consegue entender rapidamente o loop
inteiro, sem se preocupar com os detalhes da impressao da mensagem de
ajuda; "imprimir a ajuda" e' uma tarefa unica e bem definida e, portanto,
pode (e deve) ser colocada em uma funcao separada (a menos, e' claro, que
a mensagem de ajuda tenha apenas uma linha; nesse caso, pode ser mais
facil simplesmente incluir um "printf" no lugar da chamada `a funcao
usage()).

Uma "regra" citada no CodingStyle do Linux: uma funcao deve ocupar no
maximo duas telas e, se voce precisa usar uma indentacao muito "profunda"
(muitos "TABs" para a direita), provavelmente voce precisa repensar o
codigo.

Outra coisa e' o estilo para a diagramacao do codigo. Existem ferramentas
capazes de automatizar um estilo, entao "erros" nesse quesito sao menos
importantes. Nao obstante, o ideal e' definir um estilo de escrita "bom"
e, principalmente, consistente, ou seja, sempre igual ao longo do seu
programa. Como eu ja' disse, uma boa ideia e' ler o arquivo
/usr/src/linux/Documentation/CodingStyle, dar uma olhada no "gnu coding
standards" (disponivel no sitio da FSF, http://www.fsf.org) e na pagina do
prof. Feofiloff sobre o assunto,
http://www.ime.usp.br/~pf/algoritmos/aulas/layout.htm . Alias, o prof.
Feofiloff da' uma sugestao excelente e facil de seguir: use o espacamento
como se estivesse escrevendo texto comum.

Falou?

Ate' +
Nelson

--
Science is what we can tell a computer. Art is everything else. --- D.E.Knuth