En la programación de computadoras , auto-documentado (o auto-describen ) de código fuente y las interfaces de usuario siguen las convenciones de nombres y de programación estructurada convenciones que permiten el uso del sistema sin conocimiento específico previo. [1] En el 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 ]
Objetivos
Los objetivos comúnmente establecidos para los sistemas de auto-documentación incluyen:
- Facilite la lectura y la comprensión del código fuente [2]
- Minimice el esfuerzo necesario para mantener o ampliar los sistemas heredados [2]
- Reducir la necesidad de que los usuarios y desarrolladores de un sistema consulten fuentes de documentación secundaria, como comentarios de código o manuales de software [2]
- Facilitar la automatización a través de la representación autónoma del conocimiento.
Convenciones
Código autodocumentado está escrito ostensiblemente el uso de nombres legible, por lo general consiste en una frase en un idioma humano que refleja el significado del símbolo, como article.numberOfWords o TryOpen . El código también debe tener una estructura clara y limpia para que un lector humano pueda comprender fácilmente el algoritmo utilizado.
Consideraciones prácticas
Hay ciertas consideraciones prácticas que influyen en si se pueden lograr los objetivos de un sistema de autodocumentación y en qué medida.
- uniformidad de las convenciones de nomenclatura [2]
- consistencia [2]
- alcance de la aplicación y requisitos del sistema
Ejemplos de
A continuación se muestra un ejemplo muy simple de código 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.
size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ; size_t count = 0 ; while ( * text ! = '\ 0' ) { if ( is_alphabetic ( * text )) count ++ ; texto ++ ; } recuento de devoluciones ; }
Crítica
Jef Raskin critica la creencia en el código "autodocumentado" diciendo que el código no puede explicar la razón por la que se está escribiendo el programa o por qué se implementa de esa manera. [3]
Ver también
Referencias
- ^ Schach, Stephen R. (2011). Ingeniería de software clásica y orientada a objetos (8 ed.). Profesional de McGraw-Hill . págs. 505 –507. ISBN 978-0-07337618-9. OCLC 477254661 .
- ^ a b c d e Paul, Matthias R. (9 de abril de 2002). "Re: [fd-dev] ANUNCIO: CuteMouse 2.0 alpha 1" . freedos-dev . Archivado desde el original el 24 de marzo de 2020 . Consultado el 24 de marzo de 2020 .
[…] Casi cualquier valor numérico en el código fuente debe ser reemplazado 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. […]
- ^ Raskin, Jef (18 de marzo de 2005). "Los comentarios son más importantes que el código: el uso exhaustivo de la documentación interna es una de las formas más olvidadas de mejorar la calidad del software y acelerar la implementación" . Cola de ACM . Desarrollo. ACM, Inc. 3 (2). Archivado desde el original el 24 de marzo de 2020 . Consultado el 22 de diciembre de 2019 . [1] [2]
Otras lecturas
- McConnell, Steve . "Lista de verificación de rutinas de alta calidad" . Código completo .