stringtranslate.com

Código autodocumentado

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 ]

Objetivos

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

Convenciones

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.

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 se pueden lograr.

Ejemplos

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 ; } 

Crítica

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]

Véase también

Referencias

  1. ^ Schach, Stephen R. (2011). Ingeniería de software clásica y orientada a objetos (8.ª ed.). McGraw-Hill Professional . pp. 505–507. ISBN 978-0-07337618-9.OCLC 477254661  .
  2. ^ abcde 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 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. […]
  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 . Desarrollo. 3 (2). ACM, Inc. Archivado desde el original el 24 de marzo de 2020 . Consultado el 22 de diciembre de 2019 .[1][2]

Lectura adicional