O diabo mora nos detalhes: aumentando a manutenibilidade da sua aplicação

A frase “O diabo mora dos detalhes” é um provérbio famoso que nos diz que a maioria das coisas que a princípio parecem ser simples e insignificantes, no final serão as que mais darão trabalho. No contexto de codificação de software, esta frase deixa de ser um provérbio e passa a ser uma verdade absoluta.

Se você tem certa experiência com desenvolvimento de software, provavelmente já teve que manutenciar o código de outro(s) programador(es) e é neste momento que você geralmente passa por uma montanha-russa de emoções e pensamentos, passando por confusão, curiosidade, angústisa e até mesmo raiva (no pior dos casos). Isso se deve ao fato que você obviamente não conhece o código de outra pessoa, e se o autor do código não se importou muito com boas práticas de programação, a manutenibilidade do código fica ainda pior.

É fato que boas práticas de programação não são príncipios que você irá aprender da noite para o dia, leva tempo até você conseguir estruturar uma aplicação baseada nos príncípios de SOLID ou até mesmo evitar a dúplicação de código aplicando o conceito DRY. Por outro lado, pequenas boas práticas de programação não levam tempo para serem aprendidas.

Se você não conhece estes princípios, não entre em pânico, este artigo não é (integralmente) sobre grandes e famosos conceitos, este artigo é sobre detalhes.

Uma aplicação é um conjunto de detalhes

Imagine a seguinte situação, você é um programador que recentemente entrou na empresa, não conhece todo o sistema e precisa dar manutenção no seguinte trecho de código:

Se você é um fã do Guia do Mochileiro das Galáxias sabe exatamente o que o número 42 significa, se não é, está totalmente perdido. E é nesse ponto que eu quero chegar.

Veja como nomear números melhoram a legibilidade do código:

Você não precisa sequer conhecer o livro para saber que a resposta correta, é 42, visto que a constante CORRECT_ANSWER tem um nome autoexplicativo. Também sabe só de ler o código que se a variável theAnswer for igual a resposta correta, a função doSomething() será executada.

O óbvio tem natureza cultural

Quando digo que o óbvio tem caráter cultural, quero dizer que algumas coisas óbvias podem variar de cultura para cultura.

Imagine que por algum motivo você está escrevendo um código Open Source (que provavelmente será acessado e implantado no mundo todo) para bares e restaurantes, e precisa escrever uma função que barre a venda de bebidas alcoólicas para menores de idade.

Se você está no Brasil o código abaixo é óbvio para você.

No Brasil uma pessoa pode comprar bebidas alcóolicas depois de completar 18 anos e isso é óbvio para os brasileiros. Por outro lado se o seu código for implantado em um bar no Haiti esta função terá um comportamento inesperado, visto que um indivíduo pode comprar bebidas alcoólicas no Haiti a partir dos 16 anos, no Cazaquistão, é diferente, só depois dos 21.

Veja como este código pode ser melhorado:

Agrupe constantes

Aplicações modernas geralmente consomem API’s REST externas e essas API’s podem te devolver vários Status HTTP e dependendo da resposta, sua aplicação terá determinado comportamento.

Se fossemos utilizar um swtich para verificar o status de uma api e tomar uma decisão baseada nela, poderiamos fazer o seguinte código:

Perceba que a constante HTTP_STATUS é um objeto que contém alguns status HTTP que interessam para nossa aplicação.

Como todos os status são status HTTP é uma boa prática os deixarem agrupados, isso deixa claro para todos os programadores que dentro do contexto desta aplicação, todos esses códigos de status HTTP podem exisitir.

Magic Strings

Quando falamos em Magic Numbers geralmente associamos apenas a números mágicos, e esquecemos que strings também podem ser mágicas (assim como qualquer outro tipo de variável).

É comum termos flags no banco de dados para salvar o dados de um pedido, status de uma transação ou até mesmo o estado de envio. Geralmente estas flags são compostas por um único e não descritivo caractere.

Havia uma aplicação na qual trabalhei anos atrás que salvava o tipo de cartão usado no pagamento com um único caractere. Usávamos ‘C’ para quando o pagamento tinha sido feito em cartão de crédito e ‘D’ quando cartão de débito.

Naqueles tempos, não estavamos nem ai para Magic Numbers / Strings e comparavamos letra por letra na camada de aplicação, se esse código fosse optimizado, teríamos uma constante com todos os tipos de cartões.

Veja alguns exemplos que podem facilitar o entendimento do código da sua aplicação:

Tenha apenas uma fonte de constantes

Maravilha! Você entendeu que Magic Numbers e Magic Strings são um dos males da programação e compreendeu que não os deve usar, então você começa a criar constantes em todos os arquivos que pode.

Passam-se alguns minutos e você percebe que se você quiser alterar uma constante, precisa alterar 245 arquivos.

Você pode estar pensando nesse momento:

Mas isso é simples, bastar dar um localizar e substituir na aplicação inteira e pronto!

Primeiro, nunca mais pense isso. Aplicações em produção quebram por um CTRL+H mal dado, principalmente se você não usa versionamento de código. Se você utiliza muito o localizar e substituir no seu dia a dia, sua aplicação provavelmente está mal escrita.

Segundo, é uma boa prática você deixar suas constantes em um único lugar (adapte-se esta dica para sua estrutura de pastas e pattern), ou seja, imagine que você tem uma aplicação front-end com vários módulos, e o nome da sua aplicação aparece em todos estes módulos.

Você não deve declarar em todo módulo a constante APP_NAME, basta você criar um único arquivo de constantes relacionadas ao app e importar este arquivo em todos os componentes, deste modo, uma vez que você precisar alterar o nome da aplicação, você deve alterar em um único lugar e todos os componentes serão atualizados de uma única vez.

Conclusão

Conforme vimos neste artigo, a utilização de Magic Numbers pode aumentar a complexidade de uma aplicação no mesmo passo que diminui a manutenibilidade. É uma boa prática (para não dizer dever) utilizar sempre variáveis em qualquer trecho de código, seja ele um loop, condição, ou parâmetros padrões na declaração de funções. Além disso deve-se utilizar apenas uma fonte de constantes, aumentando ainda mais a manutenibilidade do código.

Este artigo é baseado no capítulo 17, seção G25 do Clean Code: A Handbook of Agile Software Craftsmanship que discorre sobre a substituição de números mágicos por constantes descritivas.