Depuração: Encontrando por Conta Própria

A maioria dos iniciantes trata um erro como uma parede. Batem nele, param, e pedem a alguém que escale para eles. O hábito que realmente constrói habilidade é diferente: você aprende a tratar um erro como uma pergunta com resposta encontrável, e você a encontra antes de pedir.

Leia a mensagem de erro como se fosse evidência, não ruído

Stack traces são constantemente ignoradas porque parecem assustadoras. Mas geralmente elas dizem exatamente onde e por que algo quebrou. Se você recebe TypeError: 'NoneType' object is not subscriptable em Python, isso não é gibberish aleatório — significa que uma variável que você esperava conter uma lista ou dict é na verdade None. O número da linha diz onde. Seu trabalho é rastrear para trás a partir dessa linha e encontrar onde o valor deveria ter sido definido mas não foi.

Faça isso antes de buscar qualquer coisa online: leia a última linha do traceback primeiro, depois trabalhe para cima. A última linha geralmente nomeia a exceção real. As linhas acima mostram a cadeia de chamadas que o levou até lá.

Reproduza deliberadamente

Se um erro só aparece às vezes, você ainda não o entende. Antes de tocar no código, tente fazer isso acontecer de forma confiável. Mude uma entrada por vez. Falha com uma lista vazia mas não com uma cheia? Falha apenas na segunda chamada de uma função, não na primeira? Um erro que você consegue reproduzir sob comando é um erro que está 80% resolvido, porque agora você pode testar se um corrigir realmente funcionou em vez de adivinhar.

Corte o problema pela metade, depois pela metade novamente

Busca binária não é apenas para arrays ordenados — é a forma mais rápida de encontrar código quebrado em uma função longa ou pipeline. Comente ou contorne a segunda metade de sua lógica e verifique se a primeira metade ainda produz o erro. Se sim, o problema está na primeira metade. Se não, está na segunda. Repita. Isso funciona para um script de 200 linhas tanto quanto funciona para um pipeline de dados com múltiplos estágios onde você verifica saídas em cada estágio com print() ou df.head().

Isso é melhor do que mudar linhas aleatoriamente e executar novamente, que é o que a maioria das pessoas faz sob pressão e desperdiça muito mais tempo do que economiza.

Use o debugger em vez de print() quando print() deixa de funcionar

Declarações print() são boas para casos simples, mas uma vez que você está rastreando estado através de múltiplas chamadas de função, um debugger real economiza tempo de verdade. Em Python, coloque import pdb; pdb.set_trace() logo antes da linha suspeita, execute o script, e você recebe um prompt ao vivo onde pode inspecionar variáveis, avançar linha por linha com n, e entrar em chamadas de função com s. O debugger integrado do VS Code faz a mesma coisa com breakpoints que você clica em vez de digitar. De qualquer forma, o objetivo é o mesmo: observe o estado real do seu programa em vez de adivinhar qual ele provavelmente é.

Isole do resto do seu projeto

Se um erro acontece dentro de uma base de código grande, não o depure dentro da base de código grande. Copie a função relevante para um arquivo novo com entrada falsa e mínima que dispara a mesma falha. Se o erro desaparecer, algo sobre o contexto circundante — uma variável global, um import, estado obsoleto — é a causa real, e você acabou de aprender algo importante. Se o erro persiste em isolamento, você agora tem um caso pequeno, compartilhável e testável, e está muito mais perto do corrigir real.

Verifique suas suposições contra a realidade, não memória

Uma enorme parte do tempo de depuração vai para suposições não questionadas: