Clean-Code

Saber dar bons nomes é uma das habilidades mais valiosas — e menos ensinadas — na engenharia de software. Em Python, nomes de variáveis e funções bem escolhidos tornam o código legível, reduzem ambiguidade e ajudam a preservar o design ao longo do tempo. Seguindo as diretrizes da PEP 8 e os princípios da Clean Architecture, este artigo mostra como criar nomes expressivos, consistentes e concisos, sem cair na armadilha dos identificadores longos ou genéricos. Você verá exemplos reais, más práticas comuns e um mini refactor que demonstra como nomes claros transformam o código. ...

A complexidade ciclomática mede o número de caminhos de execução independentes em uma função ou módulo Python, ajudando a identificar código difícil de testar e manter. Desenvolvida por Thomas J. McCabe em 1976, essa métrica é calculada como o número de pontos de decisão (if, for, while, etc.) mais um, revelando riscos em fluxos ramificados excessivos. Mas o que é Complexidade Ciclomática? Complexidade ciclomática (CC) quantifica a densidade de caminhos lógicos em um grafo de controle de fluxo. Em Python, cada estrutura condicional ou de loop adiciona ramificações: um if simples eleva a CC para 2, enquanto and/or em condições compostas multiplica caminhos independentes. A fórmula básica é CC = E - N + 2P, onde E são arestas, N nós e P componentes conectados, mas ferramentas como radon ou flake8 computam isso automaticamente. ...

Evitar números mágicos em expressões booleanas é uma recomendação explícita de linters Python modernos (como Pylint e Ruff, via regra PLR2004), pois esses valores dificultam a leitura e a manutenção do código. Entender essa regra e o contexto em que ela surgiu ajuda a justificar a prática ao time e a padronizar o estilo da base de código. PLR2004: de onde vem essa regra? A sigla PLR2004 é o identificador da regra magic-value-comparison em ferramentas de lint para Python, como o linter Ruff, que reutiliza a numeração herdada do Pylint. A regra é derivada diretamente da mensagem de refatoração R2004 – magic-value-comparison do Pylint, mantido pelo projeto PyCQA, que incentiva o uso de constantes nomeadas em vez de valores mágicos em comparações. ...

Descubra como o pattern matching no Python 3.10+ transforma árvores de if/elif em código declarativo e poderoso, superando limitações do switch case clássico. Neste guia técnico para desenvolvedores Python, explore exemplos práticos de destructuring de listas, dicionários e classes, guards e padrões compostos – otimizado para buscas como “pattern matching Python tutorial”, “match case vs switch Python” e “structural pattern matching exemplos”. O que Torna o Pattern Matching Único Introduzido pelos PEPs 634, 635 e 636 no Python 3.10, o match/case vai além da comparação de valores: descreve a estrutura de dados, desconstruindo tuplas, listas, dicionários e objetos em variáveis prontas para uso. Diferente do switch case de C/Java, que compara apenas escalares sem fallthrough automático, aqui o primeiro case que casa encerra o bloco, eliminando bugs comuns. Ideal para APIs REST, eventos JSON e parsers em projetos full-stack Python. ...

Baseado na Live de Python #150 do canal Eduardo Mendes no YouTube, este artigo explora de maneira prática e direta a “primitive obsession” — code smell onde tipos primitivos (strings, dicts, lists) substituem abstrações de domínio ricas — e como dataclasses (Python 3.7+, PEP 557) oferecem solução definitiva para criar Value Objects tipados, imutáveis e comportamentalmente ricos. Para sêniores buscando elevar modelagem DDD e reduzir technical debt em escala. Primitive Obsession: Raiz do Problema Primitive obsession ocorre quando entidades de domínio são reduzidas a “bags of primitives”, i. e., em que objetos de domínio são representados apenas como coleções simples de tipos primitivos (como strings, números, listas e dicionários) sem encapsulamento ou comportamento. Ou seja, em vez de ter classes ou estruturas que representem conceitos ricos com regras, validações e métodos, o código manipula “sacos” ou “pacotes” de dados primitivos soltos, o que aumenta a complexidade, propensão a erros e dispersa a lógica de negócio. Aplicando princípios de POO fundamentais: encapsulamento, polimorfismo e responsabilidade única. Consequências incluem: ...

A arquitetura hexagonal, ou Ports and Adapters, coloca a lógica de negócio no centro de um hexágono simbólico, cercada por portas (interfaces abstratas) que conectam adaptadores externos como bancos de dados, APIs web, filas ou serviços de terceiros. Proposta por Alistair Cockburn em 2005, ela inverte as dependências tradicionais: o domínio não conhece frameworks ou persistência, mas estes dependem dele via injeção de dependências, promovendo código limpo e adaptável em Python. Essa abordagem alinha-se perfeitamente à filosofia “simples é melhor” do Python, mas com rigor para domínios complexos. ...

Em desenvolvimento de APIs REST, status codes HTTP são tão importantes quanto o payload da resposta. Eles comunicam, de forma padronizada, o resultado de cada requisição e são consumidos por clientes, gateways, observabilidade e ferramentas de monitoração. Apesar disso, ainda é comum encontrar código repleto de “números mágicos”, como 200, 404 ou 500 espalhados pela base. Uma abordagem mais robusta é substituir esses valores literais por constantes descritivas, como HTTP_200_OK ou HTTP_404_NOT_FOUND. Essa prática aproxima o código das boas práticas de engenharia de software e melhora diretamente a legibilidade, a manutenção e a confiabilidade da API. ...

Você já enfrentou resultados inesperados ao usar listas ou dicionários como valores padrão em funções Python? Esse é um problema comum que pode causar bugs sutis e difíceis de encontrar. Neste artigo técnico, vamos desmistificar o motivo desse comportamento, mostrando exemplos práticos e como evitá-lo com boas práticas de programação. Se você é um desenvolvedor Python buscando produzir código mais robusto e previsível, este conteúdo é essencial para o seu dia a dia. ...

Entenda os riscos do uso de from módulo import * em Python, saiba por que ele compromete a legibilidade e a manutenção do código e descubra as alternativas recomendadas por desenvolvedores experientes. A armadilha da conveniência em Python Há algo em Python que seduz até os desenvolvedores mais experientes: a promessa de simplicidade. Poucas linguagens conseguem equilibrar legibilidade e poder expressivo como ele faz. Mas é justamente essa aparente simplicidade que, às vezes, nos leva a atalhos perigosos. Entre eles, um velho conhecido: from módulo import *. ...

No desenvolvimento Python, especialmente em projetos de médio a grande porte e pipelines complexos de testes automatizados, é comum encontrar erros sutis relacionados a comparações com o valor booleano True. Uma prática aparentemente inofensiva, como usar == True para verificar condições, pode introduzir comportamentos inesperados que dificultam a manutenção, geram falsos positivos em testes e causam dúvidas em revisões de código. Essas situações não são incomuns em equipes que lidam com múltiplas camadas de abstração — desde o código de negócio até frameworks de teste — e evidenciam a importância de entender profundamente a diferença entre identidade e igualdade em Python, bem como as melhores práticas para escrever condicionais claras e robustas. ...