¿Hay algún programa que pueda ayudar a entender otro programa?

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 aparecen nuevos desarrolladores y necesita arreglar algo, es posible que conozcan Java pero quizás no bash scripting. Sería bueno si hubiera un programa que ayudaría a entender qué¿Hay algún programa que pueda ayudar a entender otro programa?

for f in "[email protected]" ; do

significa. Estaba pensando en algo que crea una página HTML estática con el código más resaltado de sintaxis y si se pasa sobre algo (como el "para"), sería mostrar una ventana emergente con una explicación:

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

¿Existe ya algo por el estilo?

[EDITAR] Esto es solo un ejemplo. Obtendrá otra ayuda para f, in, "[email protected]", ; y do, es decir, se explicarán todos y cada uno de los elementos de la línea. Los elementos desconocidos (como los nombres de comando) deberían vincularse a Google. Para que pueda entender lo que hace, incluso si le falta algún detalle.

[EDIT2] Soy consciente de que no puede escribir un programa que comprenda qué 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 explicación breve lo que significa (más tal vez un enlace a alguna referencia en profundidad).

Esto es para alguien que sabe cómo programar pero que quizás no haya visto alguna construcción oscura antes. Decir

echo "Error" 1>&2

Cada programador fiesta sabe lo que esto significa, pero un desarrollador de Java podría ser confundido por el 1>&2 a pesar del hecho de que pueden adivinar que echo == System.out.println. Un simple "Redirects stdout to stderr" aclarará las cosas y dará ese instante "AHA!" lo que les permite mantenerse en su línea de pensamiento actual.

Fuente

2010-03-10 Aaron Digulla

Para alguien que no conoce bash, la parte difícil no es 'for', es' $ @ '. – mouviciel

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 deberían explicarse. Para que pueda entender lo que hace, incluso si le falta algún detalle. –

+1 Buena pregunta. : D Hay programas que pueden entender otros programas. Se llaman intérpretes/compiladores. Pero generalmente cada uno de ellos entiende un solo idioma. –

Si lo piensas bien, no es tan útil tener una herramienta que explique la sintaxis. Los desarrolladores solo pueden buscar palabras clave en Google en lugar de navegar por un sitio web de manera similar al 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 lo hace para Python).

Fuente

2010-03-10 08:54:50

Los buenos comentarios explicarán los detalles de alto nivel. Pero para mí, es obvio lo que significa "$ @" ', mientras que otro desarrollador simplemente lo mirará con frustración. Entiendo que esta herramienta no permitirá crear documentación automática; es solo una "lente inteligente" que puede responder preguntas detalladas. –

¿Por qué no agregar un comentario en línea sobre "$ @"? También puede agregar etiquetas para comentarios, como #TODO: ... o #FIXME: ... o #SEEME: ... o, en este caso, #NOTICE: "$ @" hace esta pequeña cosa ... En una nota al margen, ¿cuál sería el beneficio para alguien que no conoce bash pero conoce Java para saber qué hace "$ @", además de conocer los detalles de alto nivel? Seguramente no estás esperando que depure o arregle sin aprender bash? –

Porque no sé lo que el próximo desarrollador podría saber y seguramente no quiero explicar cada personaje en cada línea de mi código. –

Es algo muy complicado. En primer lugar, por definición, se puede demostrar que el programa que "comprenderá" cualquier programa no existe. Sin embargo, aún puede usar la documentación existente. Quizás usar herramientas como Doxygen puede ayudarte. Debería documentar su código a través de comentarios y la documentación se generará a partir de ellos.

Fuente

2010-03-10 08:56:33

Puede encontrar una herramienta que admite incluso más idiomas aquí: http://sourceforge.net/projects/naturaldocs/ –

Solo quiero que el nuevo desarrollador ahorre el esfuerzo de buscar cada detalle de un lenguaje de programación desconocido en un libro o en Google . No estoy buscando una herramienta que pueda "entender" pero que "ayude a comprender" –

Esto genera una documentación atractiva a partir de los comentarios del código fuente. Estoy buscando algo que funcione en un nivel inferior. –

IMO sería más simple y más eficaz simplemente recopilar enlaces a buenas referencias específicas del idioma y tutoriales en una página Wiki.

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

Fuente

2010-03-10 08:57:26

Sería mejor recopilar esos enlaces en una herramienta que pueda conectarlos a las partes relevantes de la referencia específica del idioma. ¿Con qué frecuencia ha intentado leer algunos perl solo para preguntarse dónde en los documentos incluso para comenzar a buscar algo? –

Entiendo el problema de la versión. Pensé que tendrías que ejecutar la herramienta en la máquina con los scripts y llamará a 'bash --version' y lo agregará a la página HTML (para que sepa qué sintaxis es la correcta). Sí, es un esfuerzo, pero no insuperable. –

@ Aaron Digulla Ah, ahora entiendo tu idea. Y suena intrigante de hecho. Todavía diría que una herramienta que enlaza con la explicación de la sintaxis para una construcción en particular es solo una ayuda superficial. Para usar un elemento de lenguaje correctamente, uno debe comprender su semántica, sus efectos secundarios ... a menudo hay muchísima complejidad subyacente. Por lo tanto, conocer la sintaxis (y solo la sintaxis) podría dar una falsa sensación de control a los desarrolladores junior. –

Un idioma no puede explicarse 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 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 profundamente bash si no sabe nada sobre los procesos & control de trabajos, variables de entorno, una gran lista de comandos de unix (tr, sort, cut, paste, sed, awk, find,. ..) y muchas otras características que no aparecen en la sintaxis.

Fuente

2010-03-10 09:01:22 mouviciel

No estoy buscando una comprensión profunda. Solo quiero una herramienta que pueda decirme qué significa "$ @". O en su ejemplo: "&" creará una ventana emergente: "Ejecuta un comando en el fondo". Si el lector necesita más información, tendrá que buscarla. Pero si nunca han visto "&" antes, ese pequeño texto podría ser suficiente. –

Mi punto es que el lector puede no entender el concepto de "ejecutar un comando en segundo plano" y al final buscará todo el lenguaje. ¿Qué es lo mejor? Pasar tiempo para implementar ventanas emergentes en cada elemento de sintaxis, pasar tiempo para enseñar bash a alguien que ya conoce a Java o pasar tiempo para contratar a alguien que ya conozca a bash y java. No elegiría la primera solución. – mouviciel

Si no entienden este concepto, al menos sabrá por qué googlear. Intenta buscar ">>" en google. –

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

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

¿Por qué es importante ayudar a los programadores de otros idiomas a comprender el código en este nivel de detalle de implementación? Cualquiera que mantenga la implementación en este nivel obviamente tendrá que conocer 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 herramienta de aprendizaje.

Fuente

2010-03-10 10:33:03 mattbh

No usaré esta herramienta para documentar mi trabajo. Lo usaré como una herramienta de mantenimiento a través de la cual el próximo desarrollador puede ejecutar cualquier script para comprender todos esos pequeños trucos que no comprende :-) –

Bien, sí, sería realmente útil para eso. Incluso algo que nombra las partes del discurso sería útil para llegar a la documentación correcta de manera más eficiente, p. decir que "> & 2" en bash es una redirección, ya que "redirección" es un buen término para buscar en la página de manual o en la web. – mattbh

Si la herramienta produce

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

sería bastante inútil. Este es exactamente el tipo de comentario que a los programadores en formación (humanos) se les dice que deben escribir.

Fuente

2010-03-10 10:46:57

-1 Lo siento, no entendiste la pregunta en absoluto. –

@ Aaron Es a menudo culpa del interrogador. –

@ Aaron: Él entendió la pregunta, usted no hizo una pregunta adecuada aunque: p. – Younes

¿Hay algún programa que pueda ayudar a entender otro programa?

Respuesta

Cuestiones relacionadas