Código autodocumentado

En programación informática , el código fuente autodocumentado (o autodescriptivo ) y las interfaces de usuario siguen convenciones de nomenclatura y convenciones de programación estructurada que permiten el uso del sistema sin conocimientos específicos previos. ^[¹^]

Objetivos

Los objetivos comúnmente establecidos para los sistemas de autodocumentación incluyen:

Hacer que el código fuente sea más fácil de leer y comprender ^{[ 2 ]}
Minimizar 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 secundarias como comentarios de código o manuales de software ^{[ 2 ].}
Facilitar la automatización mediante la representación autónoma del conocimiento.

Convenciones

El código autodocumentado se escribe, aparentemente, con nombres legibles para humanos, que suelen consistir en una frase en un idioma que refleja el significado del símbolo, como article.numberOfWords o TryOpen . Además, el código debe tener una estructura clara y ordenada para que un lector humano pueda comprender fácilmente el algoritmo utilizado.

Consideraciones prácticas

Existen ciertas consideraciones prácticas que influyen en si los objetivos de un sistema de autodocumentación pueden alcanzarse y en qué medida.

uniformidad de las convenciones de nomenclatura ^{[ 2 ]}
consistencia ^{[ 2 ]}
Alcance de la aplicación y requisitos del sistema

Ejemplos

A continuación se muestra un ejemplo muy sencillo de código C autodocumentado , que utiliza convenciones de nomenclatura en lugar de comentarios explícitos para que la lógica del código sea más evidente para los lectores humanos.

size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ;tamaño_t recuento = 0 ;mientras ( * texto != '\0' ) { si ( es_alfabético ( * texto )) contador ++ ; texto ++ ; }devolver contador ; }

Crítica

Jef Raskin criticó la creencia en el código "autodocumentado" al afirmar que el código no puede explicar la lógica detrás de por qué se escribe el programa o por qué se implementa de esa manera. ^{[ 3 ]}

Véase también

Referencias

↑ Schach, Stephen R. (2011). Ingeniería de software clásica y orientada a objetos (8.ª ed.). McGraw-Hill Professional . págs. 505-507 . ISBN 978-0-07337618-9OCLC 477254661
1 2 3 4 5 Paul, Matthias R. (2002-04-09). "Re: [ fd-dev ] ANUNCIO: CuteMouse 2.0 alpha 1" . freedos-dev . Archivado del original el 24-03-2020 . Recuperado el 24-03-2020 . [...] 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 fragmentos 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 ignoradas de mejorar la calidad del software y acelerar la implementación" . ACM Queue . Development. 3 (2). ACM, Inc. Archivado del original el 24 de marzo de 2020. Consultado el 22 de diciembre de 2019 .

Lecturas adicionales

McConnell, Steve . "Lista de verificación de rutinas de alta calidad" . Code Complete .

[Schach_2011-1] Schach, Stephen R. (2011). Ingeniería de software clásica y orientada a objetos (8.ª ed.). McGraw-Hill Professional . págs. 505-507 . ISBN 978-0-07337618-9OCLC 477254661

[Paul_2002_Symbols-2] 1 2 3 4 5 Paul, Matthias R. (2002-04-09). "Re: [ fd-dev ] ANUNCIO: CuteMouse 2.0 alpha 1" . freedos-dev . Archivado del original el 24-03-2020 . Recuperado el 24-03-2020 . [...] 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 fragmentos del código. [...]

[Raskin_2005-3] 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 ignoradas de mejorar la calidad del software y acelerar la implementación" . ACM Queue . Development. 3 (2). ACM, Inc. Archivado del original el 24 de marzo de 2020. Consultado el 22 de diciembre de 2019 .

[

[ 2 ]

[ 3 ]