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

En mi equipo tenemos un gran 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 time, las especificaciones tienden a envejecer y quedar desactualizadas

Las personas que hacen las especificaciones tienden a disgustar el control de la fuente y los progtwigdores tienden a no les gusta compartir.

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

Nop. 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 ploop. Superalo.

Las especificaciones, aunque son agradables para comenzar la progtwigción, pierden su valor con el time sin importar lo que haga. La audiencia para la especificación es un progtwigdor que no tiene mucha información. Esos progtwigdores se transforman en progtwigdores profundamente conocedores que ya no necesitan las especificaciones.

Partes de la especificación, en particular descripciones, pueden tener algún valor a largo ploop.

Si el rest de las especificaciones tiene valor, los progtwigdores las mantendrían actualizadas.

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

Los resúmenes deben tomarse de las especificaciones originales y colocarse en el código.

Se debe extraer un documento final. Este documento puede replace 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.

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

Mediawiki es una buena opción.

Realmente me gustan 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 types de documentos para esto, pero tener acceso a todo en línea y accesible desde una interfaz común es key.

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

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

Tal enfoque ciertamente mantendrá la especificación y el código sincronizados y las testings 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 time específico en el proyecto asignado para escribir (o volver a escribir) la especificación después de escribir el código. 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 loggings para garantizar que las especificaciones cambien junto con el código. Se ralentizará el process de desarrollo, pero si es realmente tan importante …

No conozco ninguna solución particularmente buena para precisamente lo que describes; en general, las únicas soluciones que he visto que realmente mantienen este tipo de cosas sincronizadas son herramientas que generan documentation del código fuente (doxygen, Javadoc).

Una técnica utilizada para mantener la documentation sincronizada con el código es la progtwigción alfabetizada . Esto mantiene el código y la documentation en el mismo file y utiliza un preprocesador para generar el código comstackble de la documentation. Por lo que sé, esta es una de las técnicas que utiliza Donald Knuth , y está feliz de pagarle a la gente dinero si encuentran errores en su código.