Como trabalhar em uma base de código desconhecida

Em nossa profissão, é comum trabalhar em uma base de código desconhecida. Isso acontece toda vez que alguém entra em um novo projeto ou mesmo precisa trabalhar em uma parte até então intocada em grandes projetos.

Esta ocorrência não se limita a um desenvolvedor ter que corrigir um bug; pode ser um arquiteto de soluções tendo que projetar um novo recurso ou um colaborador OpenSource trabalhando em um problema do GitHub em seu tempo livre. Portanto, quero descrever como abordo a situação para que possa beneficiar outras pessoas.

Um exemplo de problema

Para ilustrar meu ponto, usarei um problema comum do GitHub solicitando um novo recurso em um projeto de código aberto.

Enquanto trabalhava para a Hazelcast, eu examinava regularmente os chamados "bons primeiros problemas" para trabalhar nos hackathons. Eu nunca poderia executar tal hackathon, mas isso não vem ao caso. Minha ideia era ajudar as pessoas interessadas em contribuir com o Open Source a se familiarizarem com a base de código.

Na época, achei esta questão interessante:

Adicionar suporte para operação getQuiet http://ehcache.org/apidocs/net/sf/ehcache/Cache.html#getQuiet(java.lang.Object) ?

A ideia é conseguir pegar uma entrada sem tocá-la, ou seja, não atualizará o carimbo de data/hora do último acesso.

O caso de uso por trás disso é poder monitorar a existência de uma chave sem alterar o despejo dessa chave.

-- Mapa Distribuído: Adicionado suporte para operação getQuiet

Como colaborador do OpenSource, como abordaria o trabalho?

Diagramar é a chave

A documentação é o primeiro passo para embarcar em um novo projeto. Em um projeto regular, a documentação provavelmente estará ausente, incompleta ou parcialmente (se não totalmente) enganosa; em um hackathon, o tempo pode ser muito curto para lê-lo em detalhes.

Projetos de código aberto bem-sucedidos têm boa documentação em geral. No entanto, a documentação é voltada principalmente para usuários, raramente para desenvolvedores. Mesmo quando for o caso, as chances de que a documentação resolva o problema são baixas.

Por esse motivo, meu ponto de entrada é desenhar um diagrama. Observe que, embora algumas ferramentas possam fazer engenharia reversa de código e desenhar diagramas automaticamente, não as uso de propósito. Desenhar um diagrama manualmente tem muitos benefícios em relação a um diagrama gerado automaticamente:

• Ele se concentra em áreas do código relevantes para o problema em questão.

• Obriga o desenhista a ler e entender o código, que é a única fonte da verdade.

• Ele constrói nosso modelo mental do código.

• Ele documenta nossas descobertas para ser acessível mais tarde. No entanto, observe que o valor da documentação diminui com o tempo conforme o código subjacente evolui e ambos se separam.

Vamos criar um diagrama para o código do problema. Primeiro, vamos clonar o repositório localmente para abri-lo em nosso IDE favorito; o único recurso necessário é que, quando alguém clica em uma chamada de método, é direcionado para o método.

Para o diagrama em si, chame-me de antiquado, mas ainda sou a favor dos diagramas de sequência UML por dois motivos:

• Eu tenho alguma experiência com eles.

• A semântica não é ad-hoc , mas compartilhada entre pessoas que conhecem UML, até certo ponto.

Sem mais delongas, aqui está:

Tendo desenhado o diagrama, podemos localizar rapidamente onde está o 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. O DefaultRecordStore faz a leitura do Record , que aciona a atualização do último horário de acesso.

Corrigir o problema está fora do escopo deste post. Envolve conversar com pessoas mais familiarizadas com o projeto geral para desenvolver a melhor solução. Uma boa abordagem em um hackathon é primeiro oferecer pelo menos duas alternativas e documentar seus respectivos trade-offs.

Para o ferramental, muitas alternativas estão disponíveis. Minhas preferências vão para PlantUML :

• Ele oferece um aplicativo da web e um contêiner Docker
• Gera imagens SVG ou PNG
• é skinnable
• É de código aberto e gratuito
• É mantido regularmente

Conclusão

Compreender uma base de código existente é uma habilidade crucial, independentemente da função técnica exata de cada um. A criação de um diagrama ajuda bastante nesse objetivo, com o benefício adicional da documentação.

Gosto de diagramas UML porque estou familiarizado com eles e eles oferecem semântica compartilhada.

Portanto, se você quiser entender melhor uma base de código, precisará mais do que apenas ler seu código; você precisa desenhar diagramas.

Originalmente publicado em A Java Geek em 14 de maio de 2023