O que é qualidade de código?

Altos padrões de programação são para o processo de desenvolvimento de software o que a mise en place e  o "trabalho limpo" são para a operação de uma cozinha comercial. Práticas que elevam a qualidade de seu código podem gerar melhor funcionalidade em curto prazo, mas seus benefícios mais importantes são menos problemas, um progresso mais rápido e custos de manutenção menores no longo prazo.

Os benefícios de longo prazo de um código de maior qualidade podem, às vezes, ser difíceis de serem comunicados pelos programadores à gerência menos versada nas minúcias do ciclo de vida do desenvolvimento de software. Equilibrar os benefícios abrangentes de um código ideal com as pressões imediatas das prioridades de negócios geralmente envolve compensações complexas. Dito isso, um estudo de 2022 com 39 códigos de base de produção proprietários afirmou, entre outras descobertas,¹ que: 

• Dívida técnica decorrente de código apressado desperdiça até 42% do tempo dos desenvolvedores.

• Código de baixa qualidade leva a 15 vezes mais defeitos do que código de alta qualidade.

• Resolver problemas em código de baixa qualidade leva (em média) 124% mais tempo do que resolver problemas em código de alta qualidade.

Um código de maior qualidade aumenta a facilidade e a velocidade de compreensão, refatoração, depuração e adição de novas funcionalidades a uma base de código. Um código claro, consistente e bem escrito facilita uma coordenação mais fluida entre as equipes de desenvolvimento e reduz a complexidade e as complicações das alterações de código. Isso gera não apenas uma forte qualidade de software, mas também uma sólida experiência do desenvolvedor e do usuário.

O fato de um trecho de código compilar e executar com sucesso seu propósito no tempo de execução não é suficiente para determinar sua qualidade geral. Escrever código não é como completar um jogo de palavras cruzadas, no qual existe uma única maneira de completar sua tarefa corretamente: frequentemente há inúmeras soluções para um determinado problema de programação. Funcionalidade, portanto, representa o mero código aceitável. O valor de um código de alta qualidade se manifesta em seus efeitos secundários no contexto ao seu redor.

Código de alta qualidade é um conceito relativamente abstrato. A qualidade geral de um trecho de código é definida tanto por como ele é feito e como ele interage com a base de código mais ampla em que existe quanto por qualquer conjunto específico de métricas de qualidade de código discretas e objetivas (embora existam muitas dessas métricas).

As características comuns de um código de alta qualidade incluem:

• Legibilidade: a legibilidade do código é essencial para manutenção, depuração e coordenação entre equipes e tempo. Outro membro da equipe consegue entender facilmente seu código? Outro programador pode, daqui a muitos anos, interpretar com precisão seu código sem você estar por perto para fornecer contexto?

• Capacidade de manutenção: a complexidade do código geralmente está inversamente correlacionada com a capacidade de manutenção do código. Seu código é facilmente testável, permitindo que sua equipe o avalie com eficiência quanto a vulnerabilidades de segurança e oportunidades de otimização? Ele é robusto o suficiente para adicionar novas funcionalidades sem comprometer a funcionalidade principal, ou é muito frágil para ser ajustado sem exigir uma grande refatoração? Priorizar código sustentável pode acarretar problemas iniciais adicionais, mas economiza tempo e energia significativos no futuro.

• Eficiência: um código bem escrito pode reduzir a latência e o consumo de recursos de um sistema. Por exemplo, estruturas de dados escolhidas cuidadosamente podem minimizar o número de operações da CPU necessárias para uma determinada função. Estratégias inteligentes de armazenamento em cache de dados reduzem as operações de entrada/saída (E/S) dispendiosas, eliminando consultas redundantes ao banco de dados e solicitações de rede, enquanto a liberação imediata da memória não utilizada evita o inchaço desnecessário da RAM.

• Confiabilidade: menos defeitos e estruturas robustas a alterações de código significam falhas menos frequentes e downtime. A confiabilidade é essencial para a experiência e a confiança do usuário, bem como para a integridade dos sistemas críticos nos quais sua empresa se baseia.

Ao escreverem para a Harvard Data Science Review em 2023, pesquisadores da Calvin University, do Amherst College e da Columbia propuseram um framework prescritivo para um bom código: "Os quatro Cs".²

• Correção: o código faz o que deveria fazer. Os autores enfatizaram dois corolários dessa inclusão óbvia: "Primeiro, a exatidão é uma métrica necessária, mas insuficiente para um bom código. Em segundo lugar, os outros objetivos apoiam e promovem a correção.”

• Clareza: qualquer pessoa que leia e escreva o código pode dizer o que ele se destina a fazer e, intuitivamente, fazer as modificações necessárias.

• Contenção: evite expansão, redundância e dependências desnecessárias. A contenção adequada envolve, entre outras coisas, "usar funções para conter código reutilizável e manter o código usado em arquivos ou projetos em um módulo ou pacote".

• Consistência: Uma base de código deve manter a consistência interna de estilo, convenções de nomenclatura, comentários, indentação e outras práticas.

À medida que o desenvolvimento de software moderno continua a ser cada vez mais impulsionado por assistentes de programação agêntica, como o IBM Bob, a contenção e a consistência são particularmente úteis para maximizar a eficácia e a precisão das ferramentas automatizadas. Dito isso, a capacidade de plataformas de última geração, como o IBM Bob, de identificar oportunidades de refatoração de IA em tempo real pode reduzir o esforço necessário para impor esse nível de disciplina estilística.

Embora cada linguagem de programação e caso de uso tenha suas próprias nuances específicas e considerações granulares, existem algumas melhores práticas universais para código de qualidade em qualquer cenário.

Uma abordagem para conceituar código de alta qualidade é simplesmente pensar nele como um código que evita o máximo possível de marcadores de código ruim (que serão explorados mais adiante neste artigo).

Para uma abordagem mais normativa, o artigo mencionado acima da Harvard Data Science Review (HDSR) descreve uma série de diretrizes para garantir a qualidade do código. Embora essas diretrizes sejam ostensivamente otimizadas para as necessidades de cientistas de dados, a maioria é aplicável a qualquer disciplina de programação.

Convenções de nomenclatura fortes são essenciais para a legibilidade e consistência do código. Os autores sugerem as seguintes práticas:

• O comprimento dos nomes deve ser proporcional ao seu escopo. Quanto maior a distância (seja em termos de tempo, linhas de código ou estrutura organizacional) entre a definição inicial de um termo e seu uso, mais essencial é que seu nome comunique claramente sua função.

• Mantenha um resumo das abreviações. Nomes de variáveis curtos ou até mesmo com um caractere único podem ajudar a organizar o código, mas também podem se tornar inescrutáveis para pessoas menos familiarizadas com o projeto. Manter uma espécie de "glossário" mitiga essa compensação.

• Use letras maiúsculas de forma consistente. Também é aconselhável evitar casos em que dois nomes sejam diferenciados apenas por suas letras maiúsculas.

• Evite nomes indefinidos. Eles elevam significativamente a dificuldade de interpretação do código.

• Escolha convenções de nomenclatura de arquivos que classifiquem naturalmente. Por exemplo, você pode adotar a norma ISO 8601 para data e hora ou preencher números com 0s para garantir que todos tenham a mesma quantidade de dígitos.

Convenções de nomenclatura claras e consistentes também podem ajudar a simplificar o ato de solicitar assistentes de programação de IA e aumentar a precisão de sua saída. Por exemplo, em vez de solicitar que um agente inspecione certos tipos de variáveis ou explore todos os arquivos de um determinado intervalo de datas, o que pode exigir que seu agente de IA deduza probabilisticamente a partir do contexto quais variáveis ou arquivos atendem aos critérios, você pode explicitamente solicitar que um agente explore todos os arquivos que começam com um número específico ou todas as variáveis com um nome específico.

Além de codificar convenções de nomenclatura fortes, o ideal é que um guia de estilo abrangente deve padronizar elementos de formatação, incluindo o uso de espaços em branco e recuo, comentários e tipos de dados, bem como "dialetos de programação". Uma grande variedade de guias de estilo comprovados para várias linguagens de programação pode ser encontrada no GitHub, como os incluídos nesta lista selecionada.

Um guia de estilo também é uma referência inestimável para um assistente de programação de IA, servindo como contexto para tarefas específicas ou até mesmo como parte do prompt do sistema do agente de IA.

Aproveitar toolkits e bibliotecas é um benefício natural para a reutilização e eficiência do código, ajudando a padronizar fluxos de trabalho e saídas entre diferentes equipes e acelerar em geral a criação de código. Eles são particularmente úteis quando o código deve mediar interações com sistemas complexos de terceiros ou lidar com problemas repetitivos "resolvidos".

Mas a dependência excessiva de toolkits pode adicionar um inchaço desnecessário e introduzir dependências externas, reduzindo a robustez e a capacidade de manutenção do código. Eles também tendem a abstrair a lógica subjacente do código, diminuindo sua legibilidade. Os autores do HDSR articulam o equilíbrio ideal em termos simples: "Queremos que nosso toolkit seja o mais simples possível, mas não mais simples."

Se você fica copiando, colando e modificando com frequência os mesmos blocos de código, pode ser mais bem atendido por uma função que encapsula o código repetido em um só lugar. Os parâmetros dessa função podem refletir os elementos que mudam de instância para instância. Isso limpa o código e simplifica a manutenção, pois permite ajustar todas as instâncias dessa função em uma única etapa e local (em vez de ajustar individualmente cada duplicata de um bloco de código).

As verificações de consistência são validações automatizadas que verificam se os dados ou estados do sistema em potencial seguem regras e convenções lógicas predefinidas, ajudando a evitar e levar em conta conflitos e contradições imprevistos no código. Esses testes automáticos costumam ser um componente padrão e crítico dos pipelines de CI/CD (integração contínua/implementação contínua).

Esse é um exemplo por excelência da importância da testabilidade de código. É difícil ou impossível criar testes de unidade que validem exaustivamente todas as funções caso seu código seja muito complexo ou contenha muitas dependências fortemente acopladas.

Sistemas de controle de versão ajudam a promover processos de consistência, controle de qualidade, coordenação e avaliação de código entre as equipes. Ao usar frameworks de programação orientados por IA (especialmente aqueles que podem ajustar sua base de código de forma autônoma), certifique-se de ter um meio de reverter facilmente quaisquer alterações indesejadas ou adversas. O IBM Bob, por exemplo, automaticamente versiona seus arquivos de workspace como checkpoints para permitir uma fácil reversão de alterações de código conforme a necessidade.

Em termos gerais, código ruim é difícil de ler e manter, frágil a mudanças e novas funcionalidades, ineficiente e pouco confiável. Muitas vezes tem funcionalidade desnecessária, em que diferentes módulos estão interligados, e qualquer alteração em um requer trabalho extra para evitar a quebra do outro. Ele carece de documentação adequada e é mal organizado, desprovido de estrutura lógica coerente, uma situação frequentemente chamada de "código espaguete".

Código ruim geralmente é produto não apenas de habilidades de programação inadequadas, mas de incentivos e estrutura organizacional deficientes: a priorização excessiva do lançamento de funcionalidades em detrimento da qualidade do código normalmente gera um time to market mais rápido, mas maiores complicações futuras e dívida técnica.

É importante lembrar que código ruim geralmente funciona — pelo menos temporariamente. A dívida técnica não se acumularia se esse não fosse o caso, porque inegavelmente códigos quebrados teriam que ser resolvidos. Refactoring: Improving the Design of Existing Code, o livro seminal de Martin Fowler e Kent Beck publicado pela primeira vez em 1999 (e atualizado várias vezes desde então), portanto, utilizou o termo odores de código para descrever o código ruim. Geralmente não são bugs e não impedem inerentemente o funcionamento de um programa, mas indicam fraquezas de projeto e problemas de qualidade de código que podem retardar o desenvolvimento ou causar bugs no futuro.

A lista de odores de código de Fowler e Beck para se prestar atenção inclui exemplos como:

• Função longa (método longo): um método que contém muitas linhas de código.

• Classe grande: uma classe que tenta fazer muito e contém muitas variáveis, sem coesão.

• Obsessão primitiva: uso de tipos de dados primitivos em vez de objetos pequenos especializados.

• Nome misterioso: funções ou variáveis mal nomeadas, ocultando sua intenção real.

• Aglomerados de dados: grupos de variáveis que frequentemente aparecem juntos em todos os lugares.

• Elementos preguiçosos: classes ou funções que fazem muito pouco para existir.

• Lista de parâmetros longa: funções que exigem muitos argumentos para operar corretamente.

• Cirurgia disparada: uma alteração exige a modificação de muitos módulos dispersos simultaneamente (o que é essencialmente o oposto da classe grande).

• Código duplicado: estruturas de código idênticas ou muito semelhantes em vários locais.

Uma lista abrangente de odores de código, completa com explicações, exemplos e citações, pode ser encontrada aqui. Sua presença geralmente é um sinal de que a refatoração é necessária. Uma compreensão completa e abrangente de toda a organização desses problemas e das complicações que surgem deles é útil para estabelecer uma concepção compartilhada de padrões de qualidade entre as equipes de desenvolvimento.

A medição da qualidade do código deve sempre envolver uma avaliação qualitativa e quantitativa. Embora métricas objetivas, como complexidade ciclomática, possam ser úteis, também podem ser enganosas sem o contexto adequado.

Por exemplo, sua equipe pode escrever um pacote de testes automatizados e seu código pode atingir 100% de cobertura de código em uma bateria de testes unitários. Mas se o pacote de testes não tiver algumas das asserções significativas necessárias para validar genuinamente se seu código funciona totalmente conforme a necessidade, a falsa confiança dessa cobertura de teste pode causar mais danos do que benefícios.

Da mesma forma, uma estrutura de avaliações robusta deve incluir tanto a revisão manual do código quanto a revisão do código por IA. Uma ferramenta moderna de programação agêntica, como o IBM Bob, pode realizar extensas análises estáticas de código e refatoração em tempo real, mas se beneficia muito de regras personalizadas e modos personalizados, que transmitem as necessidades e intenções específicas do desenvolvedor. Os seres humanos não são abrangentes e a IA não é infalível, mas apoiar um ao outro é a maneira mais segura de confirmar se todos os possíveis problemas foram investigados com o contexto adequado.

Lembre-se sempre de que a qualidade do código depende do contexto. Imagine que um programador de sua equipe tenha escrito um algoritmo ou bloco de código eloquente, eficiente e perfeitamente articulado, que atinja perfeitamente a função pretendida. Se o problema pudesse ter sido efetivamente resolvido usando uma função de biblioteca incorporada padrão com a qual todos já estivessem familiarizados, esse código eloquente seria de fato um problema de qualidade, pois adiciona complexidade desnecessária e sobrecarga mental.