Google Analytics

quarta-feira, 19 de outubro de 2011

Código autodocumentado

Prezados, código auto-documentado é diferente de colocar comentários no código explicando o que ele faz ou de colocar documentação doxygen ou afins.

Código auto-documentado é código escrito de forma clara, com nomes descritivos nas entidades (variáveis, funções, constantes, etc) e com uma estruturação lógica que facilita o entendimento. Levando a um exemplo extremo, a seção abaixo não é código auto-documentado:

/* Function f(string s1, string s2)
This function prints a name on the screen, formatting as "surname, name". s1 is the name and s2 is the surname.
*/
f(string s1, string s2)
{
   ...
}

Nem que o comentário fosse no padrão doxygen, isto não seria código auto-documentado!

Agora um exemplo de auto-documentado:

//----------------------------------------------
// This function prints a name on the screen, formatting 
// as "surname, name".
printAsSurnameCommaName(string name, string surname)
{
...
}