Software em funcionamento é mais relevante que documentação abrangente. Concordamos com esse princípio expresso no manifesto ágil. Entretanto, entendemos que ele foi interpretado e utilizado de forma infeliz, como justificativa, por tempo demais, para decisões arbitrárias que levaram a um incremento no custo de desenvolvimento e manutenção de software.

Documentação abrangente é fundamental para redução do custo de manutenção de um software e, no longo prazo, é fundamental para sua evolução tecnológica.

Por que o código não é suficiente?

Há quem defenda que a máxima expressão da verdade, em um software, está em seu código. Não concordamos com isso. Entendemos que [tweet]nenhum software pode ser analisado coerentemente sem levar em conta o contexto de seu desenvolvimento (como e por quem é feito) e sua finalidade em produção (o problema que ajuda a resolver).[/tweet]

Nem sempre o código reflete as motivações de seu desenvolvimento. Aliás, com frequência, o código aponta em direção oposta (o que é, por si só, uma enorme dívida técnica).

Ao longo do tempo as motivações mudam e o código também. Infelizmente, com muita frequência, pressões e crenças (das quais, em sua maioria, não compactuo), associadas a um processo desregrado, levam a uma “erosão conceitual” – dívidas técnicas se acumulam e a expressividade é comprometida.

Mesmo quando o código expressa, de forma clara e objetiva, as motivações de seu desenvolvimento, em sistemas grandes, ele acaba sendo complexo demais para a maior parte das discussões, sobretudo as que envolvem os especialistas de domínio.

Por que os testes não são suficientes?

Há também quem defenda que o conjunto de testes, bem escrito e com bom índice de cobertura, é recurso suficiente para o entendimento de um software. Mais uma vez, não concordamos.

Os testes simplificam o entendimento de um software, sem dúvidas. Entretanto, em sistemas grandes, serão tão numerosos e tão diversos que não serão úteis para um primeiro entendimento.

Os testes tem utilidade de compreensão para a atividade operacional de escrita do código, mas não são tão relevantes para o atingimento das metas do processo de desenvolvimento em sentido mais amplo, sobretudo na composição da organização incluindo o negócio.

Por que diagramas são necessários?

Quando estamos lidando com sistemas complexos, é útil fazer análises em diferentes níveis de abstração. O código e os testes são, em última instância, as fontes com menor abstração disponível para entender o software.

Bons modelos permitem a interpretação do software em níveis mais altos de abstração, facilitando a comunicação e o envolvimento das diversas partes interessadas. Além disso, também ajudam a explicar, para quem não está envolvido no processo de desenvolvimento desde o início, o(s) problema(s) que está se tentando resolver e a solução que se está implementando.

O desenvolvimento de modelos (diagramas) que ajudem a entender o software e o domínio, em mais de um nível de abstração, faz parte dos processos de desenvolvimento e manutenção do software. Em nossa interpretação, negligenciar este fato é assumir uma dívida técnica cara demais.

Como lidar com diagramas desatualizados?

Em termos simples, com processos maduros que impedem que a desatualização aconteça.

Infelizmente, diagramas e comentários desatualizados não são submetidos a um compilador e não geram falhas de build. Há diversas iniciativas que visam gerar documentações atualizadas, a partir do código. Entretanto, acreditamos que ainda estamos distantes do dia em que essas soluções irão funcionar de forma ideal.

Nossa defesa é de que o processo profissional de desenvolvimento de software deva contemplar sempre a atualização da documentação. Entendemos que isso somente é possível se essa atualização for parte fundamental para a aplicação de modificações do código.

Aliás, entendemos que seja responsabilidade e interesse do time manter o software fácil de explicar. Se esse não for o caso, com o tempo, o custo de manutenção irá invariavelmente aumentar.

Os diagramas e modelos deveriam ser o “primeiro alvo” para análise do software e para a implementação da modificação. Em seguida, os testes e a base de código.

Não tenho diagramas para explicar meu software. E agora?

Somos avessos a complexidade e entendemos que o primeiro passo para atacar a complexidade é permitir discussões em diferentes níveis de abstração.

O primeiro passo para atacar uma realidade complexa é a construção de modelos simplificadores.

Se seu time não mantem diagramas para explicitar diferentes níveis de abstração da sua solução, entendemos que tenha uma enorme dívida técnica que irá se revelar em grande dificuldade, sobretudo de manutenção e evolução tecnológica. PAGUE ESSA DÍVIDA!

Não tenho “competência” para elaborar diagramas. O que fazer?

Entendemos que os skills necessários para elaborar e manter uma boa documentação não sejam comuns a todos os desenvolvedores. Nem achamos que essa seria uma pré-condição.

A manutenção de diagramas, entretanto, é skill fundamental para o arquiteto de software.

Já afirmamos, mais de uma vez, que não entendemos que o arquiteto de software seja, necessariamente, um developer senior-senior. Embora concordemos que a maioria dos bons arquitetos que conheço o sejam.

O arquiteto de software, como orquestrador, tem a responsabildiade e atribuição de garantir que o sistema tenha diagramas atualizados e efetivos.

Na prática…

Se seu software não tem documentação abrangente (abstrações, em diversos níveis, que explicam o software), você tem uma dívida técnica. Pague-a!

Embora exista a possibilidade do “time” manter a documentação, é potencialmente mais barato concentrar essa responsabilidade e desenvolver essa competência em alguns membros, geralmente com outras atribuições de arquitetura.

O processo de desenvolvimento será mais efetivo se considerar o processo de análise e desenvolvimento de soluções, começando pela documentação e em seguida no código.

Vamos continuar essa conversa?

Sempre recorremos a ideia de que “são as cicatrizes que contam a história do guerreiro”. Compartilhamos aqui algumas de minhas cicatrizes. Adorariamos saber um pouco das suas. Se possível, compartilhe um pouco da realidade em sua empresa…