Metodología para documentar la base de código existente

Trabajo como parte de un equipo en una aplicación existente que no tiene documentación en línea, ni tampoco tiene documentación técnica. Como he estado trabajando en varios informes de errores en la aplicación, he escrito una especie de ruta de navegación para mí: números de errores en varios lugares para que el próximo desarrollador pueda consultar ese número de error para ver qué estaba sucediendo.

Mi pregunta es así:

¿Cuál es el método más eficiente para documentar este código? ¿Debería documentar al tocar el área (el método del virus, si lo desea), o debería documentar desde cada sección por sí solo, y no seguir caminos que se ramifican en otras áreas de la aplicación? ¿Debo insertar comentarios en línea donde no existía ninguno anteriormente (con el temor de que pueda terminar identificando incorrectamente lo que hace el código)?

¿Qué método usaría para documentar con precisión y rapidez una aplicación bastante grande que no tiene documentación en línea existente, ni referencias en línea a documentación externa?

Documentar bases de código heredadas

Recomiendo seguir la regla de exploración con bases de código heredadas. Intentar documentar un proyecto heredado independientemente de trabajar en él simplemente nunca sucederá.

Documentación en código

Lo más importante es utilizar las funciones de documentación en el entorno de desarrollo elegido, por lo que significa pydoc para python, javadoc en java o comentarios xml en C #. Esto facilita la escritura de la documentación al mismo tiempo que escribe el código.

Si confía en volver y documentar las cosas más tarde, es posible que no lo haga, pero si lo hace mientras escribe el código, entonces lo que necesita documentarse estará fresco en su mente. C # incluso tiene la opción de emitir una advertencia de compilación si la documentación XML está incompleta o es inconsistente con el código real.

Pruebas como documentación

Otro aspecto importante es tener una buena integración y pruebas unitarias.

A menudo, la documentación se concentra en lo que las clases y los métodos hacen de forma aislada, omitiendo cómo se usan juntos para resolver su problema. Las pruebas a menudo los ponen en contexto al mostrar cómo interactúan entre sí.

Del mismo modo, las pruebas unitarias a menudo señalan dependencias externas explícitamente a través de las cuales las cosas deben ser simuladas .

También encuentro que usando el desarrollo basado en pruebas escribo un software que es más fácil de usar, porque lo estoy usando desde el principio. Con un buen marco de prueba, hacer que el código sea más fácil de probar y que sea fácil de usar a menudo es lo mismo.

Documentación de nivel superior

Finalmente, hay qué hacer con el nivel del sistema y la documentación arquitectónica. Muchos abogarían por escribir dicha documentación en una wiki o usar Word u otro procesador de textos, pero para mí el mejor lugar para dicha documentación también es junto al código, en un formato de texto sin formato que sea amigable con el sistema de control de versiones.

Al igual que con la documentación en código, si almacena su documentación de nivel superior en su repositorio de código, es más probable que la mantenga actualizada. También obtiene el beneficio de que cuando extrae la versión XY del código, también obtiene la versión XY de la documentación. Además, si usa un formato compatible con VCS, significa que es fácil bifurcar, diferenciar y fusionar, al igual que su código.

Me gusta bastante primera , ya que es fácil de producir las dos páginas en HTML y documentos PDF a partir de ella, y es mucho más amigable que LaTeX , sin embargo, todavía puede incluir expresiones matemáticas de LaTeX cuando los necesite.

Pregunta capciosa. Básicamente, usaría el método de "refactorización", que repetiría como "si tocas el código, documentalo".

Pero para ser precisos; a medida que surgen problemas, y como debe familiarizarse con el código para corregir los errores que ocurren, yo diría que debe usar esa familiaridad para escribir comentarios sobre ese código en particular; en esencia, la motivación para corregir el error en ese momento te ha obligado a familiarizarte lo suficiente con el código para poder documentarlo. Y por esa razón, desconfiaría de seguir ramas no relacionadas O de documentar funciones no relacionadas, porque en ese punto, si no está realizando pruebas activas del código (para verificar su corrección de errores), es difícil ser totalmente seguro de que comprende exactamente lo que hace el código y por qué. (No me estoy metiendo en el problema de que también puede ser difícil determinar con precisión qué y por qué el código hace lo que hace incluso cuando se prueba una corrección de errores; usted '

Este enfoque debería tender a maximizar la precisión, con un sacrificio de la velocidad general, pero no afectar su necesidad de mantener el código demasiado severamente al mismo tiempo. Si sus tareas de corrección de errores son pequeñas, por supuesto, puede aventurarse en "territorio desconocido" y comenzar a documentar allí, pero si usted (como la mayoría de nosotros) no puede encontrar suficiente tiempo en el día para arreglar el código y documentarlo, esto Es un buen compromiso.

Una cosa vale la pena notar también; Debe tener una buena documentación externa. Usted dice que su código no tiene referencias a documentación externa; Sin embargo, espero por su bien que dicha documentación externa exista. Si no, realmente haría que escribir esa documentación externa sea su primera prioridad; Creo que algo en el nivel de una especificación funcional es absolutamente crítico para todos los grandes proyectos de software. La razón es que las especificaciones funcionales, o la documentación de alto nivel de esa forma, pueden ayudar a prevenir el "arrastre de características" o la "deriva de características" en cualquier software; y la deriva de características (en particular) puede ser destructiva para la documentación, ya que puede hacer que la documentación quede desactualizada. (Defino el arrastre de características como la adición progresiva (y molesta) de características a una pieza de software; deriva de características, por otro lado, es donde el conjunto de acciones que realiza el software cambia lentamente con el tiempo. El arrastre de características es ADITIVO, es decir, generalmente implica aumentar el conjunto de funcionalidades del software; la deriva de la característica, por otro lado, es suma cero; uno por uno, una pieza de funcionalidad de borde se define para hacer algo diferente, hasta que el software esté haciendo algo completamente diferente de lo que se pretendía originalmente. La deriva de funciones es rara, pero DEMORTA para la documentación).

Una aplicación que co-desarrollé en el transcurso de dos años tenía una grave falta de documentación. En algún momento quedó claro que pasaríamos la aplicación a otro desarrollador que la mantendría a partir de ese momento, por lo que tuvimos que documentar el código.

Para tratar con el alcance gigantesco del proceso de documentación, trataría de documentar todo el código en una función específica o parte de la aplicación en un día determinado. No tenía ningún patrón en particular, sino una insistencia en hacer algo cada día y obtener una sensación de finalización al documentar diariamente un archivo completo o una sección de la aplicación.

Tardó meses en documentar toda la solicitud, pero a la media hora (máx.) Al día realmente nunca se comió el cronograma del proyecto y evitó mucho del tedio que acompaña a la documentación.

Utilizamos la documentación XML en C #, y proporcionó suficientes características y estructuras para facilitar la documentación. Incluso si no está documentando una aplicación C #, el patrón de tener un breve resumen seguido primero por comentarios fue muy útil.

Documentaría como agregué / modifiqué el código. Aparte de eso, también documentaría API públicas o cualquier interfaz entre módulos. Si documentara todo el código, es posible que no vea el ROI por el tiempo dedicado. Puede ser útil usar algo como un wiki para organizar la documentación externa a medida que la desarrolla. El documento más útil al que hice referencia cuando comencé en mi último proyecto fue el documento de arquitectura. Incluía información sobre las tecnologías utilizadas y proporcionaba una vista de alto nivel de cómo se aplicaba la aplicación en capas.

Yo usaría los comentarios de Doxygen. Doxygen tiene más formatos de salida que la mayoría de los otros formatos gratuitos y es fácil de aprender.

Incluso podría considerar contratar a un contratista para hacer esto, ya que algunos de nosotros lo hacemos para vivir. Sin embargo, con esta opción aún debe comprometerse a revisar los documentos.

Otra técnica común es asignar el nuevo desarrollador para documentar el código. Luego, haga que cada persona nueva lo atraviese a medida que avanza. Tenga en cuenta que algunos desarrolladores consideran esto como un tratamiento de conducto, necesario solo en los casos directos, LOL.

Antes de comenzar a documentar cualquier cosa, desarrolle un estándar. Esto puede ser tan simple como asegurarse de escribir algunas líneas sobre un encabezado de función o clase en algo más oficial y detallado (como javadoc). Antes de que alguien pueda registrar el código, su documentación debe cumplir con ese estándar.

Lo que encontré funciona bien es agregar comentarios bien escritos antes del encabezado de la función a las funciones que he creado que no estaban documentadas anteriormente, y agregar comentarios en línea a todo lo que he agregado. Desea evitar documentar el código que no ha tocado. Es peor tener malos comentarios que no tener comentarios, y si estás documentando esto 'rápidamente', probablemente escribirás malos comentarios.