Cómo trabajar en una base de código desconocida

En nuestra profesión, es común trabajar en un código base desconocido. Sucede cada vez que uno se une a un nuevo proyecto o incluso necesita trabajar en una parte previamente intacta en los grandes.

Esta ocurrencia no se limita a que un desarrollador tenga que corregir un error; puede ser un arquitecto de soluciones que tenga que diseñar una nueva función o un colaborador de OpenSource que trabaje en un problema de GitHub en su tiempo libre. Por lo tanto, quiero describir cómo abordo la situación para que pueda beneficiar a otros.

Un problema de ejemplo

Para ilustrar mi punto, usaré un problema común de GitHub que solicita una nueva función en un proyecto de código abierto.

Mientras trabajaba para Hazelcast, escaneaba regularmente los llamados "buenos primeros problemas" para trabajar en hackatones. Nunca podría organizar un hackatón de este tipo, pero eso no viene al caso. Mi idea era ayudar a las personas interesadas en contribuir con Open Source a familiarizarse con el código base.

En ese momento, encontré este tema interesante:

Agregar soporte para la operación getQuiet http://ehcache.org/apidocs/net/sf/ehcache/Cache.html#getQuiet(java.lang.Object) ?

La idea es poder obtener una entrada sin tocarla, lo que significa que no actualizará la última marca de tiempo a la que se accedió.

El caso de uso detrás de esto es poder monitorear la existencia de una clave sin cambiar el desalojo de esa clave.

-- Mapa distribuido: agregue soporte para la operación getQuiet

Como colaborador de OpenSource, ¿cómo abordaría el trabajo?

Diagramar es clave

La documentación es el primer paso para embarcarse en un nuevo proyecto. En un proyecto regular, la documentación probablemente estará faltante, incompleta o parcialmente (si no totalmente) engañosa; en un hackathon, el tiempo puede ser demasiado corto para leerlo en detalle.

Los proyectos exitosos de código abierto tienen buena documentación en general. Sin embargo, la documentación está principalmente orientada a los usuarios, rara vez a los desarrolladores. Incluso cuando es el caso, las posibilidades de que la documentación aborde el problema son bajas.

Por esta razón, mi punto de entrada es dibujar un diagrama. Tenga en cuenta que, si bien algunas herramientas pueden aplicar ingeniería inversa al código y dibujar diagramas automáticamente, no las uso a propósito. Dibujar manualmente un diagrama tiene muchos beneficios sobre uno generado automáticamente:

• Se enfoca en áreas del código relevantes para el tema en cuestión.

• Obliga al dibujante a leer y comprender el código, que es la única fuente de verdad.

• Construye nuestro modelo mental del código.

• Documenta nuestros hallazgos para que sean accesibles más adelante. Sin embargo, tenga en cuenta que el valor de la documentación disminuye con el tiempo a medida que el código subyacente evoluciona y ambos se separan.

Vamos a crear un diagrama para el código del problema. Primero, clonaremos el repositorio localmente para abrirlo en nuestro IDE favorito; la única característica requerida es que cuando uno hace clic en una llamada de método, uno es dirigido al método.

Para el diagrama en sí, llámame anticuado, pero sigo prefiriendo los diagramas de secuencia UML por dos razones:

• Tengo algo de experiencia con ellos.

• La semántica no es ad-hoc sino compartida entre personas que saben UML, hasta cierto punto.

Sin más preámbulos, aquí está:

Habiendo dibujado el diagrama, podemos ubicar bastante rápido dónde está el problema:

 public abstract class AbstractCacheRecordStore<R extends CacheRecord, CRM extends SampleableCacheRecordMap<Data, R>> implements ICacheRecordStore, EvictionListener<Data, R> { protected long onRecordAccess(Data key, R record, ExpiryPolicy expiryPolicy, long now) { record.setAccessTime(now); // 1 record.incrementAccessHit(); return updateAccessDuration(key, record, expiryPolicy, now); } //... }

1. DefaultRecordStore lee el Record , lo que desencadena la actualización de la última hora de acceso.

Arreglar el problema está fuera del alcance de esta publicación. Implica hablar con personas más familiarizadas con el diseño general para desarrollar la mejor solución. Un buen enfoque en un hackathon es primero ofrecer al menos dos alternativas y documentar sus respectivas compensaciones.

Para las herramientas, hay muchas alternativas disponibles. Mis preferencias van a PlantUML :

• Ofrece una aplicación web y un contenedor Docker.
• Genera imágenes SVG o PNG
• es personalizable
• Es de código abierto y gratuito.
• Se mantiene regularmente

Conclusión

Comprender una base de código existente es una habilidad crucial, independientemente del rol técnico exacto de uno. La creación de un diagrama contribuye en gran medida a este objetivo, con el beneficio adicional de la documentación.

Me gustan los diagramas UML porque los conozco y ofrecen una semántica compartida.

Por lo tanto, si desea comprender mejor una base de código, necesita algo más que simplemente leer su código; necesitas dibujar diagramas.

Publicado originalmente en A Java Geek el 14 de mayo de 2023