¿Cuál es la mejor plataforma para explicar el pseudocódigo a un desarrollador que no sabe nada al respecto? [cerrado]

8

Soy una persona científica que necesita documentar el código complejo de Matlab para entregarlo a un desarrollador para que lo comprenda y programe en un idioma diferente. En el pasado, usé MS Word (explicando cada paso del programa como una nueva fila en una tabla), y luego Excel, pero tampoco me pareció particularmente adecuado para mostrar mi código Matlab e ingresar comentarios de manera clara y concisa manera de documentarlo.

Me pregunto si hay alguna mejor técnica para comunicar el pseudocódigo a un desarrollador. ¿Algún software existente (gratis?) U otra plataforma (por ejemplo, TextWrangler) particularmente adecuado para proporcionar código y algún método para explicarlo? Con la esperanza de aprender de las experiencias de otros haciendo lo mismo. Gracias por adelantado.

Después de leer algunos comentarios, déjenme intentar explicar más ... Supongo que todos los desarrolladores conocen el pseudocódigo, pero no asumo que muchos conocen el código Matlab. Por lo tanto, si escribo en pseudocódigo, puedo ignorar el código de Matlab (o proporcionarlo como referencia, etc.). Pero mi pregunta es realmente más simple ... ¿hay algún software o plataforma que la gente haya usado en el pasado para comunicar claramente el código a un desarrollador? ¿Algo que permita a la persona que crea el documento describir fácilmente el código? Por ejemplo, puede incrustar el código de los códigos de color del software (un color para comentarios, otro para palabras reservadas (if, then, else, for, etc.), etc.) y en un lado hay espacio para que ingrese explicaciones y referencias, etc. Intenté hacer esto usando productos de MS, pero pensé que ya que hay una industria de personas que necesitan hacer lo mismo,

pseudocode gkdsp
fuente
1
Me pregunto si esta pregunta está mal redactada o si no estoy entendiendo bien. ¿Cómo podría un desarrollador no entender qué es el pseudocódigo? ¿Estás hablando de documentos de alto nivel sobre cómo funciona el programa?
Daenyth
44
¿Por qué darle al desarrollador un pseudocódigo? ¿Por qué no darles ese código de Matlab y dejar que lo conviertan ellos mismos? Un desarrollador decente debería poder aprender Matlab y descubrir cómo funciona el programa.
FrustratedWithFormsDesigner
1
Creo que está describiendo a un desarrollador que no sabe nada sobre MatLAB, lo que es incluso comprensible ya que el primero es un lenguaje de programación muy especializado. Lo que sospecho que está preguntando el OP es algo similar a "¿Conoces algún sistema / proceso / procedimiento comprobado que facilitará la transición para alguien que no tiene conocimiento de MATLAB para familiarizarse con él y traducir el código a otro lenguaje de programación? " Pero entonces, soy solo yo, ¡podría estar equivocado!
Andrea Raimondi
1
La palabra debería ser adecuada. Hay dos enfoques que podría tomar. Orientando la página en modo horizontal y presentando su código MATLAB en el lado izquierdo y sus anotaciones en el lado derecho. O retrato y alternar entre código y exposición.
GEL
1
Si yo fuera el desarrollador, me gustaría saber que %comienza un comentario, y luego me gustaría agregar comentarios explicativos al código de Matlab. Y déjame volver con preguntas sobre cosas que no tenían sentido para mí. Eso sería más fácil en todos los sentidos.
btilly

Respuestas:

4

pon el código MATLAB en ms-word; cambiar la fuente a courier (monoespacio) si ayuda

resalte cada línea y use Insertar comentario (debajo de la pestaña Revisión en la palabra 2010) para ingresar su explicación

el desarrollador puede hacer lo mismo; Word hará diferentes cuadros de comentarios para cada uno de ustedes

Steven A. Lowe
fuente
Gracias Steven, este es el tipo de respuesta que esperaba ver. Pensé en hacer esto en realidad, pero esperaba que hubiera algún método alternativo dedicado a tal tarea para los programadores (no ser uno yo mismo). Gracias
gkdsp
@gkdsp: es probable que exista, pero es probable que todos los que oferten en el proyecto tengan ms-word
Steven A. Lowe
44
@Stephen A. Lowe: Como chico de Linux / Mac, odio cuando la gente asume que tengo ms-word.
btilly
@btilly: La mayoría de la gente lo hace. A menos que tenga una razón filosófica o moral para no hacerlo, también debería hacerlo. De lo contrario, está causando problemas innecesariamente para usted y (potencialmente) para otros.
Richard
2
@btilly: abre tu oficina y deja de quejarte ;-)
Steven A. Lowe
2

Contrataría a un programador que ya esté familiarizado con Matlab. Menos dolor en todos los sentidos para todos. Hay muchos ex matemáticos trabajando en el desarrollo de software :-)

TrojanName
fuente
2
+1: si el desarrollador que tiene no está dispuesto a aprender Matlab, busque un mejor desarrollador. Además, si no está dispuesto a aprender Matlab, ¿qué tan bien puede hacerlo en la traducción?
Kevin Cline
Definitivamente creo que sería mucho más fácil encontrar a alguien que ya conozca a Matlab y lograr que aprendan el segundo idioma, en lugar de viceversa. (¡A menos que el segundo idioma sea algo aún más oscuro y difícil de aprender! LOL)
TrojanName
1

¡Pizarron!

La sintaxis de MATLAB está bastante lejos en comparación con un lenguaje de procedimiento "normal" (~ = para no es igual !!!!?), Por lo que documentar cada línea de código probablemente no será demasiado útil (una transformación de matriz de una línea en MATLAB a menudo se traducirá a unos cientos de líneas de código C, por ejemplo).

¿Por qué no pasar un poco de tiempo analizando la funcionalidad del programa con el desarrollador frente a una pizarra con una computadora portátil con (o una copia impresa) del código a mano? De esa manera, puede quedar atrapado en los bits difíciles de entender del programa en sí, no en la sintaxis de MATLAB.

Si realmente espera que lo traduzcan a un idioma diferente, no quiere que tengan que conocer los entresijos de cómo MATLAB procesa de todos modos, probablemente no se traducirá muy bien a otros idiomas, MATLAB es Muy especializado para trabajar con matrices. Realmente solo necesita que sepan que necesita multiplicar la matriz A por el producto B y hacer X con la salida.

Ed James
fuente
Estoy de acuerdo Ed. Una línea de código de Matlab podría ser muchísimo más en otro idioma. Es por eso que no creo que sea suficiente simplemente suministrar el programa Matlab. Con respecto a la pizarra, eso requiere que estés en la misma ciudad / estado / país, lo que generalmente no es posible. Además, estoy generando documentos para que las empresas oferten por el proyecto. Necesito explicar lo que quiero que hagan antes de decidir sobre el equipo o la persona que lo hará.
gkdsp
1
Oh hombre. No te envidio, O la compañía que gana la oferta.
Kevin
Ah, no notó la falta de proximidad física en la pregunta, así que lamento que esto no sea un ajuste brillante. He tenido el trabajo de trabajar con MATLAB en numerosas ocasiones y, en lo que a mí respecta, el código fuente sería efectivamente inútil a menos que ambos estén bien versados ​​en MATLAB para empezar y también bien versados ​​en lo que realmente hace el código . Definitivamente, trataría de utilizar algún tipo de método gráfico para transmitir el mensaje, como diagramas de flujo o algo así. ¿Quizás un montón de diagramas de actividad UML (no puedo creer que sugiera esto) podría ser apropiado?
Ed James
1
Para ser honesto, si tuviera un montón de código formateado, texto e imágenes intercalados, probablemente elegiría LaTeX y lo exportaría a un PDF. El gran beneficio de LaTeX sobre Word es que realmente puede manejar bien el código (que nunca he logrado que Word lo haga correctamente).
Ed James
1
whitebord + videorecorder
1

¿Qué tal usar herramientas de revisión de código como Rietveld o ReviewBoard?

Puede agregar comentarios y discusiones que no forman parte del código Matlab en sí.

Lie Ryan
fuente
0

Soy una persona científica que necesita documentar el código complejo de Matlab para entregarlo a un desarrollador para que lo comprenda y programe en un idioma diferente. En el pasado, usé MS Word (explicando cada paso del programa como una nueva fila en una tabla), y luego Excel, pero tampoco me pareció particularmente adecuado para mostrar mi código Matlab e ingresar comentarios de manera clara y concisa manera de documentarlo.

Bueno, Word podría funcionar ... supongo. Define diferentes estilos para diferentes partes del código (comentarios en verde, código en ...). Sin embargo, no estoy seguro de cuánto es esto práctico en realidad. ¿Qué tiene de malo simplemente exportarlo como HTML y servir al desarrollador en cuestión? Siempre puede usar la ayuda en línea, si hay un problema, si él / ella todavía no tiene instalado MATLAB.

Después de leer algunos comentarios, permítanme tratar de explicar más ... Supongo que todos los desarrolladores conocen el pseudocódigo, pero no asumo que muchos conocen el código Matlab. Por lo tanto, si escribo en pseudocódigo, puedo ignorar el código de Matlab (o proporcionarlo como referencia, etc.).

Como estás traduciendo el código MATLAB y dices que eres una persona científica, ¿se puede suponer que las ecuaciones matemáticas podrían ser una alternativa viable?

Nota de precaución, aunque ... a veces las funciones de MATLAB utilizadas NO son las que se describen en la ayuda. Pruebe su nuevo código a lo largo del camino.

Torre
fuente