En programación informática , el código fuente y las interfaces de usuario autodocumentados (o autodescriptivos ) siguen convenciones de nomenclatura y convenciones de programación estructurada que permiten el uso del sistema sin conocimientos específicos previos. [1] En desarrollo web , la autodocumentación se refiere a un sitio web que expone todo el proceso de su creación a través de documentación pública, y cuya documentación pública es parte del proceso de desarrollo. [ cita requerida ]
Los objetivos comúnmente establecidos para los sistemas de autodocumentación incluyen:
El código autodocumentado se escribe aparentemente con nombres legibles para humanos, que suelen consistir en una frase en un lenguaje humano que refleja el significado del símbolo, como article.numberOfWords o TryOpen . El código también debe tener una estructura clara y ordenada para que un lector humano pueda comprender fácilmente el algoritmo utilizado.
Hay ciertas consideraciones prácticas que influyen en si se pueden lograr los objetivos de un sistema de autodocumentación y en qué medida se pueden lograr.
A continuación se muestra un ejemplo muy simple de código C autodocumentado , que utiliza convenciones de nomenclatura en lugar de comentarios explícitos para hacer que la lógica del código sea más obvia para los lectores humanos.
tamaño_t count_alphabetic_chars ( const char * texto ) { si ( texto == NULL ) devuelve 0 ; tamaño_t conteo = 0 ; mientras ( * texto != '\0' ) { si ( es_alfabético ( * texto )) contar ++ ; texto ++ ; } devolver recuento ; } Jef Raskin criticó la creencia en el código "autodocumentado" al decir que el código no puede explicar la razón detrás de por qué se escribe el programa o por qué se implementa de tal manera. [3]
[…] casi cualquier valor numérico en el código fuente debería reemplazarse por un símbolo correspondiente. Esto mejoraría enormemente el aspecto autoexplicativo del código fuente y facilitaría significativamente el mantenimiento del código a largo plazo, ya que permitiría buscar símbolos para encontrar relaciones entre diferentes extractos del código. […]