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".
{
...
}
Por acaso, comentávamos deste assunto ontem, no bar (comendo sanduíches e bebendo suco, a idade chega para todos).
ResponderExcluirIMHO, o comentário no código auto-documentado, além de desnecessário, é confusão em potencial. Uma modificação no comportamento da função poderia torná-la, apesar de correta e facilmente entendível, conflitante com o comentário. O que fazer ao encontrar isso no código? Corrigir o comentário para refletir o comportamento da função ou corrigir a função para refletir o que seria esperado dela de acordo com o comentário?
Concordo com tua HO. :-)
ResponderExcluirRelembrando um dos princípios básicos do desenvolvimento de software: Não se repita! (www.lgmoreira.com/2011/02/as-regras-de-ouro-do-desenvolvimento-de.html). Comentar código auto-documentado, é se repetir.