Holas, toy desarrollando un programita cuya función es cifrar ficheros mediante una clave.
Me cuesta un poco decidir cual es la manera más clara de exponer el funcionamiento del algoritmo. Y como lo quiero liberar bajo licencia GNU, en plan código abierto y todo eso; pues me gustaría hacerlo lo mejor posible... ¿Qué me recomendáis? ¿Usaríais dibujitos esquemáticos?. Por favor, dadme alguien alguna idea para poder exponerlo lo mejor posible.
Gracias Por Vuestro Tiempo...
Un dicho
Envite19 Julio 2005 - 9:50pm
No sé si te servirá de ayuda o si te liará más:
"Muéstreme su código y escóndame sus estructuras de datos, y no seré capaz de averiguar siquiera para qué sirve su programa. Muéstreme sus estructuras de datos, y no necesitré ver su código para entenderlo".
Es decir, ponle nombres adecuados a las variables, define bien sus ámbitos, usa estructuras de datos en los datos que vayan relacionados siempre... Lo que se llama un código claro. Cuanto más claro sea en este sentido el código, menos documentación necesitarás en él, hasta un cierto límite, claro. Yo pongo comentarios hasta en las funciones de 2 líneas, no ya para decir lo que hacen, sino para aclarar de donde pretendo que sean llamadas y a qué se refieren los datos que suelen tener como entrada. Así, la siguiente vez que lo leo (o cuando alguien lo lee) puedo entender no ya la función, que basta con leerla, sino por qué la hice así y no asada.
No estoy de acuerdo con lo que dices, pero defenderé con mi vida tu derecho a decirlo.
- Voltaire -
Una combinación de las dos cosas.
enclaro19 Julio 2005 - 1:30pm
Me explico. Una chapada de texto puede hacer que el lector se pierda en la explicación. Un pequeño dibujo o diagrama puede hacerle ver la extructura del programa de un vistazo y localizar en un momento dado su situación en el texto rápidamente en el diagrama.
Un dibujo, esquema o diagrama por si solo puede dejar en el aire muchas cosas.
No es mi intención darte más trabajo, bastante generosidad muestras con liberar tu trabajo. Solo quiero hacerte ver, que en mi opinión, un diagrama al lado de un texto explica muy bien las cosas.
Lo primero está hecho
Strapping19 Julio 2005 - 10:39am
Holas Envite, gracias por la respuesta; te comento... en la UNI la profa de programación siempre me dijo que no hacía falta que comentase todo con tanto detalle... vamos, que comento en cada cachito de programa que es lo que pasa...
Aunque más que para una publicación, lo hago para que si pasa tiempo de una sesión de programación a otra, sepa porqué puse ese código, cómo funcionaba,... así que vamos, comentado está bien, y estructurado tb.
La cosa es que no se como mostrar el funcionamiento... si a modo de diagrama de flujo, o si simplemente a modo de chapada de texto...
Gracias Por Vuestro Tiempo
Lo primero
Envite19 Julio 2005 - 10:10am
Lo primero es que el propio código sea claro: bien ordenadito, bien estructurado, y sobre todo bien comentado. Lo demás viene después.
De paso... ya que comentarás el código, échale un vistazo a doxygen. Yo no lo uso en mis desarrollos, pero igual es lo que tú necesitas.
No estoy de acuerdo con lo que dices, pero defenderé con mi vida tu derecho a decirlo.
- Voltaire -