Mejores prácticas para entregar el código heredado

En un par de meses, un colega se mudará a un nuevo proyecto y yo heredaré uno de sus proyectos. Para prepararme, ya he ordenado a Michael Feathers ' Working Effectively with Legacy Code' .

Pero estos libros, así como la mayoría de las preguntas sobre código heredado que encontré hasta ahora, están relacionadas con el caso de heredar código tal como está. Pero en este caso, realmente tengo acceso al desarrollador original y tenemos algo de tiempo para una entrega ordenada.

Algunos antecedentes sobre el fragmento de código que heredaré:

• Está funcionando: no hay errores conocidos, pero a medida que los requisitos de rendimiento sigan aumentando, algunas optimizaciones serán necesarias en un futuro no muy lejano.
• Sin documentar : hay prácticamente cero documentación a nivel de método y clase. Sin embargo, lo que se supone que debe hacer el código en un nivel superior se entiende bien, porque he estado escribiendo en contra de su API (como recuadro negro) durante años.
• Solo pruebas de integración de nivel superior: solo hay pruebas de integración que prueban la interacción adecuada con otros componentes a través de la API (nuevamente, recuadro negro).
• Nivel muy bajo, optimizado para la velocidad: debido a que este código es central para todo un sistema de aplicaciones, gran parte de él se ha optimizado varias veces a lo largo de los años y es de nivel extremadamente bajo (una parte tiene su propio administrador de memoria para ciertas estructuras) /archivos).
• Simultáneo y sin bloqueo: si bien estoy muy familiarizado con la programación concurrente y sin bloqueo y he contribuido algunas piezas a este código, esto agrega otra capa de complejidad.
• Base de código grande: este proyecto en particular tiene más de diez mil líneas de código, por lo que no hay forma de que me expliquen todo.
• Escrito en Delphi: solo voy a presentar esto, aunque no creo que el idioma esté relacionado con la pregunta, ya que creo que este tipo de problema es independiente del idioma.

Me preguntaba cómo pasaría el tiempo hasta su partida. Aquí hay un par de ideas:

• Obtener todo para construir en mi máquina: aunque todo se debe verificar en el control del código fuente, quién no se ha olvidado de registrar un archivo de vez en cuando, por lo que probablemente este sea el primer orden del día.
• Más pruebas: si bien me gustaría realizar más pruebas unitarias a nivel de clase para que cuando realice cambios, cualquier error que presente pueda detectarse desde el principio, el código tal como está ahora no es comprobable (clases enormes, métodos largos, demasiados dependencias mutuas).
• Qué documentar: Creo que, para empezar, sería mejor centrar la documentación en aquellas áreas del código que de otro modo serían difíciles de entender, por ejemplo, debido a su naturaleza de bajo nivel / altamente optimizada. Me temo que hay un par de cosas allí que pueden parecer feas y que necesitan una refactorización / reescritura, pero en realidad son optimizaciones que han estado ahí por una buena razón que podría extrañar (cf. Joel Spolsky, Cosas que deberías Nunca lo hagas, parte I )
• Cómo documentar: Creo que algunos diagramas de clase de la arquitectura y diagramas de secuencia de funciones críticas acompañadas de algo de prosa sería lo mejor.
• A quién documentar: Me preguntaba qué sería mejor, que él escribiera la documentación o que me la explicara, para que yo pueda escribir la documentación. Me temo que las cosas que son obvias para él, pero no para mí, no estarían cubiertas adecuadamente.
• Refactorización mediante programación de pares: es posible que esto no sea posible debido a limitaciones de tiempo, pero tal vez podría refactorizar parte de su código para que sea más fácil de mantener mientras todavía estaba cerca para proporcionar información sobre por qué las cosas son como son.

Por favor comente y agregue a esto. Como no hay suficiente tiempo para hacer todo esto, estoy particularmente interesado en cómo priorizarías.

Actualización: a medida que finaliza el proyecto de entrega, he ampliado esta lista con mis propias experiencias en esta respuesta a continuación .

Cuando tenga acceso al desarrollador, codifique y pregunte: -

• Qué módulos fueron los más difíciles de codificar / implementar. Cuáles fueron los problemas y cómo se superaron.

• Qué módulos han generado la mayoría de los errores.

• Qué módulos han resultado en los errores más difíciles de resolver.

• De qué trozos de código está más orgulloso.

• Qué bits de código realmente le gustaría refactorizar, pero no ha tenido tiempo.

Estas preguntas le darán una idea de lo que le causará la mayoría de los problemas y, quizás lo más importante, un manejo de los procesos de pensamiento y las perspectivas del desarrollador original.

Como el proyecto de entrega ha terminado, creo que me tomaría el tiempo y escribiría mi propia respuesta que contiene las cosas que me funcionaron mejor.

• Obtener todo bajo control de versiones: después de asegurarme de que todo lo que necesitaba para construir estaba bajo control de versiones, también busqué en el disco duro del desarrollador anterior, para buscar scripts o utilidades adicionales que serían útiles para implementar y / o probar la aplicación, pero no No se ha registrado.
• De arriba hacia abajo: comenzaría con una mirada de alto nivel a las clases principales y una visita guiada con el antiguo desarrollador de las áreas principales. Luego cavaba más en el resto por mi cuenta, marcando cosas que no tenían sentido para mí con //TODOmarcadores.
• Escribir toda la documentación yo mismo: aunque hice que el desarrollador anterior revisara mi escritura para asegurarse de que estaba bien, insistí en escribir todo yo mismo. De esta manera, estaría seguro de que la escritura tenía sentido para mí y no solo para el desarrollador anterior.
• Comentarios en todas partes: agregué resúmenes de documentación XML a cada clase y cada método. De esta manera, me aseguré de haber visto al menos cada fragmento de código y tener suficiente comprensión para resumir lo que hizo en una oración. También facilitó la comprensión de los métodos utilizando métodos / clases de resumen, ya que IntelliSense recoge esta información. También pude identificar fácilmente áreas del código que aún tenía que mirar.
• Documento cerca de la fuente: para facilitar la conexión entre el código fuente y la documentación, pongo la mayor parte de mi documentación en el código fuente. Para la documentación de alto nivel que describe la interacción entre varios subsistemas, utilicé un wiki, ya que poner esta información en un solo lugar del código no funcionó. Toda la documentación debe ser electrónica y de texto completo.
• Diagramas: para obtener una descripción general básica, utilicé diagramas de clases de varias granularidades para los diferentes subsistemas. Para las partes concurrentes, los diagramas de objetos e interacción han sido realmente útiles; vea también mi otra pregunta sobre el tema .
• Refactorización en pareja: aunque realicé algunas refactorizaciones con el antiguo desarrollador para tener una idea del código y hacer que las cosas sean más fáciles de mantener, este fue un proceso lento y riesgoso, debido a la falta de buenas herramientas de refactorización y un montón de desagradables dependencias entre las distintas partes. El trabajo eficaz de Michael Feathers con Legacy Code es una muy buena ayuda para esto, a pesar de que refactorizar sin el soporte adecuado de herramientas sigue siendo doloroso. Mientras refactorizaba, le dejaba tener el control del mouse y el teclado, ya que era más divertido para él de esta manera (ver también mi último punto) y tenía la libertad de escribir lo que estaba aprendiendo.
• Registros separados para comentarios y cambios: después de que accidentalmente introduje un error al escribir un comentario sobre un override, he tenido cuidado de hacer comentarios y cambios en registros separados. Utilicé una pequeña utilidad para eliminar todos los comentarios del código fuente antes de registrar algo, por lo que una diferencia de un registro de solo comentario mostraría 0 diferencias. Todos los cambios (por ejemplo, la eliminación de campos no utilizados) fueron cuidadosamente revisados ​​por pares con el desarrollador anterior para asegurarse de que no estaba eliminando las cosas que aún se necesitaban.
• Tutorial línea por línea de pasajes críticos: para los pasajes más optimizados / complejos, repasaría el código línea por línea con el desarrollador anterior y, a veces, incluso con un tercer colega. De esta manera, entendí bien el código y, a medida que más personas investigaron el código, en realidad identificamos algunos errores y algunas cosas que podrían optimizarse aún más.
• Sea rápido y mantenga motivado al antiguo desarrollador: me di cuenta de que el antiguo desarrollador estaba cada vez menos interesado a medida que se acercaba su último día (no es sorprendente). Por lo tanto, me aseguraría de que las partes más críticas fueran entregadas primero, dejando el resto para que yo lo descubriera por mi cuenta, si fuera necesario. También traté de dejarle las cosas más divertidas (por ejemplo, el control del teclado cuando programo en pareja) y hacer las cosas aburridas, como escribir documentos yo mismo.
• Identificar solicitudes de características: me pareció útil pedirle al desarrollador anterior una lista de características que la gente había pedido pero que aún no se habían agregado. Hubo algunas cosas que para mí parecían simples de agregar, pero donde había una buena razón por la que no se agregaron, ya que habrían roto otras cosas cuando se implementaron de la manera que pensé al principio.

Después de haber estado en una situación similar, creo que vale la pena considerar lo siguiente:

• Asegúrese de que puede realizar y probar una implementación: realice su propia implementación del producto, desde cero, y verifique que sea idéntica a la realizada por la persona que se va. Esto aseguraría que cualquier script e instrucciones sean claros para usted, y detectaría cualquier descuido accidental, como que los ingredientes no se hayan registrado en su sistema de control de versiones. (No estoy diciendo que esto podría suceder, sólo que si ha sucedido, será mucho más fácil de tratar ahora, antes de que la persona salga)

  (Esto puede no ser relevante para usted, por ejemplo, si ya realiza la integración continua o la implementación continua, pero vale la pena mencionarlo, por si acaso ...)

• Escribir más pruebas: esta es una muy buena manera de evaluar su comprensión de un sistema. Le permitirá (u obligará) a mirar más de cerca las áreas del código, y confirmará que el código está tan libre de errores como sospecha, o revelará áreas donde pensó que entendía la intención, pero que en realidad usted necesita pedirle aclaraciones a su colega antes de irse

• Escritura en pareja de documentación: esta es una forma efectiva de escribir resúmenes. Estoy sugiriendo que usted consigue su colega para describir una característica o área, y luego que escribirlo, en la documentación, en sus propias palabras. Descubrimos que esto era enormemente más fácil cuando lo hacían dos personas juntas.

Yo pondría la redacción de las pruebas como una prioridad más alta que la redacción de la documentación, personalmente, ya que las pruebas probablemente le darán más, o más firme, comprensión.

Con respecto a la refactorización mediante programación de pares , lo único que diría es que existe el peligro de que esto se convierta en un pozo sin fondo, especialmente dado que usted dijo que solo tiene pruebas de alto nivel. Es posible que termine usando mucho más tiempo disponible de lo que pretendía.

¡+1 por las respuestas que ya tienes en tu pregunta!

La visita guiada de
10k líneas de código es mucho, pero creo que todavía no es imposible que el otro tipo te dé una 'visita guiada'. Se sientan juntos frente al código y él los lleva a un viaje de arriba a abajo, trabajando en las 'capas'. Tendría que hacerlo en ráfagas cortas: todo de una vez los mataría a ambos.

Acercar, alejar
La ventaja de hacer esto es que mientras te lo está explicando, seguramente tendrá algunos momentos de "oh, sí, también hay esto" que tal vez no lo haría si solo estuviera tratando de documentarlo. por su cuenta. Y sus preguntas ayudarán a centrarse en los bits obvios para él pero no para nadie más. Este tipo de interacción de acercamiento / alejamiento solo es posible uno a uno, intentar escribir o leer algo así es difícil de manejar.

Documentación
Creo que ambos deberían documentar cosas de forma independiente: él debería comenzar desde abajo (en caso de que no tengan tiempo para llegar juntos), y deberían comenzar desde arriba, en base a lo que han entendido su visita guiada y como si fuera para otra persona [en un trabajo anterior heredé una carga de código 'heredado', y solo tuve tiempo de documentarlo antes de dejarme :)].

Donde es que
El objetivo de la mayoría de esto es que puedas tener una idea de dónde suceden las cosas. Entonces, dado un error o modificación en particular, puede encontrar rápidamente el lugar en el código en el que necesita concentrarse. Puede probarse a sí mismo tomando la lista de errores antiguos y ver si puede predecir con precisión dónde estaba el problema.

Bombearlo para que se seque
No importa si termina odiándote (sonríe), tu trabajo es obtener tanta información del cerebro de ese chico como sea posible en el tiempo disponible. Asegúrese de contar con la administración de su lado, y de que prioricen la transferencia de conocimiento sobre "solo arreglar esos últimos errores antes de que se vaya" (a menos que los esté arreglando juntos ...).

Sugiero lo siguiente (además de lo que ya está identificado): primero, pídale a su gerente que le de tiempo para trabajar con este tipo tanto como sea posible e intente sentarse con él cada vez que se le encargue hacer un cambio. No tienes que saber todo lo que está haciendo, pero trata de atrapar tanto como puedas. Lo más importante es ser amigo de él.

Trate la entrega como un proyecto y ponga en marcha un plan e involucre a la gerencia.

0 - Asegúrese de saber cómo usar el sistema.

1 - Haga un inventario claro de los componentes de la solución, la fuente de cada uno y dónde se encuentra (en diferentes repositorios)

2 - Obtenga y, si es posible, administre las contraseñas de los diferentes servidores a partir de ahora. Asegúrese de tener toda la información de la cuenta de administrador

3 - Obtenga las licencias de cada componente externo a menos que esté fuera de su alcance (por ejemplo, dlls especiales, base de datos, etc.)

4 - Obtenga un informe escrito sobre el estado actual del sistema del desarrollador y sus clientes (si son locales de su empresa)

5 - Obtenga la documentación de las reglas comerciales, fórmulas de cálculo, etc. Puede hacer esto con él. Pídale correos electrónicos, información de reuniones, documentos de requisitos del usuario, documentos de diseño y similares que se le darán.

6 - Obtenga una lista de eventos programados (ejecuciones mensuales de trabajos, ejecuciones semanales de trabajos) a las que el software debe responder

7 - Conozca los procedimientos de copia de seguridad / restauración

8 - Comprender el marco (s) utilizado en la construcción de la aplicación

9 - Conozca las modificaciones solicitadas / esperadas / planificadas y el estado de cualquier solicitud de usuario pendiente. Comience a tratar de identificar cómo hacerlo por su cuenta.

10 - Asegúrese de que sus entornos de prueba y desarrollo sean muy similares.

11 - Intente identificar las principales dependencias (en otros sistemas o entre componentes) que no se pueden detectar fácilmente.

12 - Identifique y documente las versiones requeridas de cada uso de software y su contacto con el proveedor (si es necesario)

13 - Identifica las herramientas especiales que estaba usando que no tienes, en caso de que puedan ayudarte.

14 - Obtenga un flujo de sistema de alto nivel. y comienza a construir tu biblioteca de documentación

15 - Comprenda cómo administrar la seguridad del usuario para la aplicación

16 - Obtenga el registro de errores e intente comprender las acciones y cómo la acción afectó los datos más antiguos (si corresponde)

17 - Conozca los procesos que toman demasiado tiempo y qué necesita observar (por ejemplo, tamaños de archivo inusuales, ftp de archivos duplicados, etc.) cuando corresponda.

18 - Verifique el reloj del servidor de producción

19 - Identifique dónde están las configuraciones y compare la configuración de cada entorno con la producción para saber qué parámetros son diferentes y por qué

20 - Obtén la información de contacto de este chico

21 - Si el sistema es interno, programe una reunión con los usuarios del sistema (necesita saber quiénes son y cuál es el papel que desempeña cada uno) y se les presentará. Escuche lo que tienen que decir sobre el sistema y sobre sus problemas actuales, si los hay. Asegúrese de estar incluido en los correos electrónicos lo antes posible (después de la aprobación de su gerente)

22 - Evalúe su comprensión 1 semana antes de que se vaya e informe cualquier problema que vea como un riesgo

Como mencionó que no tiene una base de datos, esta lista se acortó.

Buena suerte.

Consideraría primero las partes más complicadas y optimizadas para el rendimiento. Le pediría que primero documente esas partes y se las explique una por una, luego trataría de escribir pruebas contra esas partes (incluidas las pruebas de rendimiento antes y después, para que pueda ver si una nueva optimización mejora o empeora las cosas) ) y que la otra persona revise las pruebas. De esta manera, documenta y explica, usted usa la explicación para escribir pruebas (mientras él está documentando un área diferente), y su revisión lo ayudará a asegurarse de que comprende lo que debería estar probando. De esa manera, también obtiene una cobertura de prueba adicional para algunas de las partes más críticas de la aplicación y la documentación de las optimizaciones de rendimiento especializadas.

Si hay tiempo después de cubrirlos, luego pasaría por un proceso similar con las partes de la aplicación que más frecuentemente han necesitado cambios a través de los años pero que no están en el primer grupo de cosas documentadas.

Luego documente todo lo que quede.

Creo que la mejor manera de asimilar un código grande es un enfoque de arriba hacia abajo. Primero trate de comprender el panorama general, y luego profundice gradualmente en los componentes uno por uno.

Ahora, en cada nivel de excavación, pídale que priorice las partes que necesitan más atención. Pídale que le explique lo más posible, pero que siempre lo documente usted mismo.

La mejor parte de documentarlo usted mismo es que cuando regrese más tarde, no tendrá problemas para recordar el mismo estado cognitivo en el que se encontraba cuando se lo explicó. Puede comprender mucho más fácilmente lo que escribió que lo que hizo otra persona. En mi experiencia, dos personas que documentan el mismo código no producen textos similares.

Esto, supongo, también resuelve sus problemas de "qué y cómo documentar". Cuando él le explica todo, puede decidir qué desea que se documente cuando regrese al código, y documentar solo esas partes.

La idea es primero entender completamente el código (en su presencia), y luego escribir / hacer todo lo que le permita asimilarlo más tarde (en su ausencia).

Al comprender completamente el código, quiero decir que necesita tener una idea del panorama general, y cómo cada componente se relaciona con este panorama general. Me ha resultado especialmente útil hacer un seguimiento de cómo cada pieza suma el todo. No intentes comprender nada de forma aislada, nunca pierdas de vista su contexto.

Por último, una vez que haya hecho lo anterior, tome el control de manera proactiva. Decida usted mismo para qué piezas necesita cobertura de prueba de unidad. qué partes deben optimizarse (o pueden optimizarse), cómo puede refactorizar algún componente, etc. Confíe en que si conoce el sistema, puede tomar todas las decisiones una vez que se haya ido.

Lo siento por ti.

Algunas sugerencias

1. ¡Grabe cada conversación que tenga con el programador que se va!
2. Pida la motivación detrás de los "grandes" problemas. Es bueno que comprenda la API, pero busque las decisiones internas: ¿por qué se dividió el código tal como está? ¿Cuáles son las responsabilidades?
3. Haz un esfuerzo para estudiar realmente el código. Cuando asume tareas de mantenimiento y soporte, a veces existe la presión de "estudiar el código mientras progresa". Resiste si puedes y realmente estudia el código.
4. Busca escenarios. Conoce la API: vea cómo se comporta el código. Un ejemplo que viene a la mente es el de un módulo de fax. Como usuario de la API, los preparadores tuvieron que preparar una imagen de página y enviar al código un comando para transmitir la página. Pídale al programador saliente que rastree con usted el código para ver cómo se lleva a cabo este escenario. Luego, por supuesto, vaya al escenario "página de recepción".
5. 80/20: primero trate de cubrir los escenarios más comunes.
6. Considere una reescritura. Si el código es antiguo y las interfaces están bien definidas, tal vez la tecnología ha cambiado lo suficiente como para justificarlo.
7. Odio decir esto, pero considera buscar un nuevo trabajo.

Si desea una documentación decente, compre una copia de Pascal Analyzer (PAL) de manera razonable y sin dolor . Lo he usado en proyectos de Delphi y fue genial; ahora pueden haber dividido la funcionalidad de la documentación en un producto con el que no estoy familiarizado (Navegador Pascal) por lo que es posible que tenga que comprar ambos (<300 USD), pero PAL fue una gran herramienta para comprender dónde se usaban las variables desde dónde se llamaban las funciones, etc. y detectar todo tipo de problemas potenciales con el código.

Use PAL para tener una idea de cómo está estructurado el código más probablemente una lista de aproximadamente 1000 mejoras sugeridas si mi experiencia es algo para continuar. Trabajar en la lista mejorará la calidad del código, lo simplificará enormemente y facilitará su vida en el futuro. Delphi es compatible con la refactorización en versiones recientes (los últimos 5 años más o menos). Necesitabas incluir todo en el archivo dpr para que realmente funcione correctamente cuando lo estaba haciendo, así que tenlo en cuenta.

Si desea pruebas unitarias, descargue DUnit y comience a crear algunas pruebas con el codificador original; esa es probablemente una forma constructiva de utilizar al menos parte de su tiempo.

Aunque no ha mencionado sobre una base de datos de back-end, pero suponiendo que haya una que debería

1. Obtenga el modelo de datos documentado especialmente las columnas y PK-FK
2. Configure un seguimiento de sql y registre todas las consultas que se disparan mientras usa la aplicación. El orden de ejecución de las consultas le dará una buena idea sobre el flujo de la aplicación y también ayudará en la depuración

Estoy en la misma situación en la que nuestro arquitecto se mudó a Australia y dejó mucho legado, ya que estuvo con la compañía de los últimos 8 años. Él mismo heredó cosas heredadas del arquitecto anterior que era contratista.

Usted y otros ya han mencionado buenos puntos, pero aquí hay problemas que enfrentamos después de que él se fue, puede ser que pueda prepararse mejor ...

1) (Persona técnica) Datos de contacto de los clientes con los que está tratando.

2) Su cuenta bajo la cual compró licencias de software, claves que deben renovarse cada año y procesos / costos para renovarlas.

3) Documento de configuración de bibliotecas / componentes de software de terceros y productos que se integran con sus productos. Luchamos durante 4 días para recuperar una máquina que se había perdido debido a que la TI había despejado el espacio y se les había dado alguna instrucción incorrecta.

4) Documentos / pasos que se utilizan para depositar el código fuente en el software Las empresas de depósito, por ejemplo, Escrow

5) Todavía hay una lista larga pero puede que no sea aplicable a usted. Ninguna cantidad de documentación puede reemplazar a una persona real, así que tenga a mano sus detalles, manténgase en buenos términos y buena suerte :)

Además, no sé si es la primera vez para ti. Para mí, he trabajado con 5/6 empleadores y siempre he heredado el código con mala documentación o sin ninguna documentación. Entonces, junto con toda la documentación, solo manténgase positivo :)