¿Cómo mantener el código y las especificaciones sincronizados? - ¿hay buenas herramientas?

Question

En mi equipo tenemos un excelente sistema de control de fuente y tenemos excelentes especificaciones. El problema que me gustaría resolver es cómo mantener las especificaciones actualizadas con el código. Con el tiempo, las especificaciones tienden a envejecer y se vuelven obsoletas

Las personas que hacen las especificaciones tienden a disgustar el control de la fuente y los programadores tienden a no gustar compartir.

Me encantaría saber qué soluciones usan otras personas. ¿hay un medio feliz en algún lado?

Answer 1

Creo que una wiki que no sea Sharepoint es buena para mantener la documentación actualizada. La mayoría de las personas no técnicas pueden entender cómo usar una wiki, y la mayoría de los programadores estarán más que felices de utilizar una buena wiki. El wiki y los sistemas de control de documentación en Sharepoint son torpes y frustrantes de usar, en mi opinión.

Mediawiki es una buena opción.

Me gustan mucho los wikis porque son, de lejos, el dolor más bajo para adoptar y mantener el ritmo. Le dan control automático de la versión, y suelen ser muy intuitivos para que todos puedan usar. Muchas empresas querrán usar Word, Excel u otros tipos de documentos para esto, pero tener acceso a todo en línea y accesible desde una interfaz común es clave.

Answer 2

No conozco ninguna solución especialmente buena para lo que estás describiendo exactamente; en general, las únicas soluciones que he visto que realmente mantienen este tipo de cosas sincronizadas son herramientas que generan documentación del código fuente (doxygen, Javadoc).

Answer 3

Una técnica utilizada para mantener la documentación sincronizada con el código es literate programming. Esto mantiene el código y la documentación en el mismo archivo y utiliza un preprocesador para generar el código compilable de la documentación. Por lo que sé, esta es una de las técnicas que usa Donald Knuth, y está feliz de tener pay people dinero si encuentran errores en su código.

Answer 4

Nope. No hay un medio feliz. Tienen diferentes audiencias y diferentes propósitos.

Esto es lo que aprendí como arquitecto y escritor de especificaciones: Las especificaciones tienen poco valor a largo plazo. superarlo.

Las especificaciones, aunque es agradable para comenzar la programación, pierden su valor con el tiempo sin importar lo que haga. La audiencia para la especificación es un programador que no tiene mucha información. Esos programadores se transforman en programadores profundamente conocedores que ya no necesitan las especificaciones.

Las partes de la especificación, en particular las descripciones, pueden tener algún valor a largo plazo.

Si el resto de las especificaciones tiene valor, los programadores las mantendrán actualizadas.

Lo que funciona bien es usar comentarios incrustados en el código y una herramienta para extraer esos comentarios y generar la documentación actual en vivo. Java hace esto con javadoc. Python lo hace con epydoc o Sphinx. C (y C++) usan Doxygen. Hay muchas opciones: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Las vistas generales deben sacarse de las especificaciones originales y colocarse en el código.

Se debe extraer un documento final. Este documento puede reemplazar las especificaciones utilizando las vistas generales de las especificaciones y los detalles del código.

Cuando se requieren revisiones generales, habrá nuevas especificaciones. Puede haber una necesidad de revisiones a las especificaciones existentes. El punto de partida son los documentos de especificación generados automáticamente. La especificación los autores pueden comenzar con esos y agregar/cambiar/eliminar al contenido de su corazón.

Answer 5

Tanto como sea posible, la especificación debe ser ejecutable, a través de rspec o doctest y marcos similares. La especificación del código debe documentarse con pruebas unitarias y un código que tenga métodos y variables bien definidos.

Luego, la documentación de la especificación (preferiblemente en una wiki) debería brindarle una visión general de las cosas a mayor nivel, y eso no cambiará mucho ni se desalineará rápidamente.

Este enfoque sin duda mantendrá la especificación y el código en sincronización y las pruebas fallarán cuando se desincronicen.

Dicho esto, en muchos proyectos, lo anterior es una especie de pastel en el cielo. En ese caso, S. Lott tiene razón, superarlo. No se mantienen sincronizados. Mire la especificación como la hoja de ruta que recibieron los desarrolladores, no un documento de lo que hicieron.

Si tener una especificación actual es muy importante, entonces debe haber un tiempo específico en el proyecto asignado para escribir (o volver a escribir) la especificación después de el código está escrito. Entonces será preciso (hasta que el código cambie).

Una alternativa a todo esto es mantener las especificaciones y el código bajo el control de la fuente y revisar los registros para garantizar que las especificaciones cambien junto con el código. Se ralentizará el proceso de desarrollo, pero si realmente es tan importante ...