programming languages - top - ¿Hay algún programa que pueda ayudar a entender otro programa?

top programming languages 2018 (6)

Necesito documentar el software en el que estoy trabajando actualmente. El software consta de varios lenguajes de programación y scripts que me hicieron pensar. Si llega un nuevo desarrollador y necesita arreglar algo, es posible que conozcan Java pero tal vez no bash scripting. Sería bueno si hubiera un programa que ayudara a entender qué

for f in "$@" ; do

medio. Estaba pensando en algo que crea una página HTML estática con el código más el resaltado de sintaxis y si se desplaza sobre algo (como "for"), aparecerá una ventana emergente con una explicación:

for inicia un bucle que itera sobre todos los valores que siguen in . En el bucle, puede acceder a cada valor a través de la variable $f . El cuerpo del bucle está entre do y done

¿Ya existe algo así?

[EDITAR] Esto es solo un ejemplo. Obtendrá otra ayuda para f , in "$@" ; y do , es decir, todos y cada uno de los elementos de la línea deben ser explicados. Los elementos desconocidos (como los nombres de comandos) deben vincularse a Google. Así que puedes entender lo que hace, incluso si te estás perdiendo algún detalle.

[EDIT2] Soy consciente de que no se puede escribir un programa que entienda lo que hace otro programa. Lo que estoy buscando es una herramienta simple que haga "resaltado de sintaxis extendida" en el sentido de que coloreará una expresión y dará una breve explicación de lo que significa (además de un enlace a alguna referencia en profundidad).

Esto está destinado a alguien que sabe cómo programar, pero tal vez no haya visto alguna construcción oscura antes. Decir

echo "Error" 1>&2

Todos los programadores de bash saben lo que esto significa, pero un desarrollador de Java puede confundirse con 1>&2 pesar del hecho de que pueden adivinar que echo == System.out.println . Un simple "Redirecciona stdout a stderr" aclarará las cosas y dará ese instante "AHA!" lo que les permite permanecer en su línea de pensamiento actual.

En mi opinión, sería más sencillo y más efectivo simplemente recopilar enlaces a buenas referencias y tutoriales específicos del idioma en una página de Wiki.

Para todos los idiomas principales, tales fuentes existen y se mantienen regularmente. Si intenta crear su propia referencia, también debe mantenerla. Justo, la sintaxis de bash no va a cambiar muy a menudo, pero otros lenguajes se desarrollan más rápido, por lo que será una carga.

Es una cosa muy complicada. En primer lugar, por definición, se puede probar que el programa que "entenderá" cualquier programa no existe. Sin embargo, todavía puede utilizar la documentación existente. Tal vez el uso de herramientas como Doxygen pueda ayudarte. Necesitará documentar su código a través de comentarios y la documentación se generará a partir de ellos.

Si la herramienta produce

for comienza un bucle que itera sobre todos los valores que siguen. En el bucle, puede acceder a cada valor a través de la variable $ f. El cuerpo del bucle está entre hacer y hacer.

Sería bastante inútil. Este es exactamente el tipo de comentario que los programadores (humanos) aprendices deben escribir.

Si lo piensas bien, no es tan útil tener una herramienta que explique la sintaxis. Los desarrolladores pueden simplemente buscar palabras clave en lugar de navegar por un sitio web de forma similar a http://www.codeweblog.com/source/ .

Creo que los buenos comentarios serán mucho más útiles, además, hay herramientas para extraer la documentación mediante el uso de los comentarios (por ejemplo, HappyDoc hace eso para Python).

Un lenguaje no se puede explicar solo a través de su sintaxis. El entorno de ejecución juega un papel importante, junto con la filosofía subyacente del lenguaje y las libraies.

Además, la sintaxis no es tan compleja para la mayoría de los lenguajes comunes (dado que el código se ha escrito teniendo en cuenta la capacidad de mantenimiento).

Continuando con el ejemplo de bash, no puede comprender a fondo bash si no sabe nada sobre procesos y control de trabajo, variables de entorno, una gran lista de comandos de Unix (tr, ordenar, cortar, pegar, sed, awk, buscar, ...) y muchas otras características que no aparecen en la sintaxis.

Una herramienta como esta podría construirse usando ANTLR , es decir, analizar el código en un árbol de sintaxis abstracta usando una gramática ANTLR para ese idioma, y escribir un generador de HTML que produjera el código anotado.

Suena como una herramienta útil para aprender idiomas o para explorar el código fuente de los proyectos que no está manteniendo, pero ¿es apropiado para la documentación?

¿Por qué es importante ayudar a los programadores de otros lenguajes a entender el código en este nivel de detalle de implementación? Cualquier persona que mantenga la implementación en este nivel obviamente tendrá que saber el idioma y probablemente tendrá un IDE para hacer la mayor parte de esto.

Dicho esto, definitivamente consideraría una herramienta como esta como una ayuda para el aprendizaje.