18

Atualização: a página do MCVE já foi atualizada e agora aponta para o link contendo o texto traduzido.


Na página do exemplo Mínimo, Completo e Verificável, ao final do texto, há um link para o artigo How to debug small programs, do Eric Lippert.

No SOen, o link deste artigo é muito usado em comentários de perguntas ruins, principalmente nas que são do tipo "meu código não funciona, encontrem o erro pra mim".

Creio que tal artigo seria útil também para o SOpt, já que recebemos muitas perguntas do mesmo estilo. Como geralmente são perguntas de iniciantes (que ainda não aprenderam a usar um debugger), creio que o artigo seja útil para os respectivos AP's.

Só que o artigo está em inglês e não encontrei nenhuma tradução para o português. Por isso entrei em contato com o autor (que autorizou) e tomei a liberdade de traduzí-lo.

Minha proposta é que o texto traduzido fique no meta (talvez como parte do FAQ? não sei). Com isso, ele poderá ser facilmente linkado nos comentários (da mesma forma que costumamos fazer com o Manual de como NÃO fazer perguntas). Quem sabe possamos também atualizar o link na página do MCVE.

Claro que isso não vai impedir que as perguntas ruins continuem chegando, mas acho que isso vai mais na linha de tentar "educar" os usuários, mostrando porque aquela pergunta não é adequada. E idealmente, fará com que a pergunta seja melhorada (é raro, eu sei, mas acho que vale a pena tentar).

O texto original está abaixo. A tradução ficará separadamente em uma resposta, conforme sugerido nos comentários.


Texto original:

How to debug small programs

One of the most frequent categories of bad questions I see on StackOverflow is:

I wrote this program for my assignment and it doesn't work. [20 lines of code].

And… that's it.

If you're reading this, odds are good it's because I or someone else linked here from your StackOverflow question shortly before it was closed and deleted. (If you're reading this and you're not in that position, consider leaving your favourite tips for debugging small programs in the comments.)

StackOverflow is a question-and-answer site for specific questions about actual code; "I wrote some buggy code that I can't fix" is not a question, it's a story, and not even an interesting story. "Why does subtracting one from zero produce a number that is larger than zero, causing my comparison against zero on line 12 to incorrectly become true?" is a specific question about actual code.

So you're asking the Internet to debug a broken program that you wrote. You've probably never been taught how to debug a small program, because let me tell you, what you're doing now is not an efficient way to get that problem solved. Today is a good day to learn how to debug things for yourself, because StackOverflow is not about to debug your programs for you.

I'm going to assume that your program actually compiles but its action is wrong, and that moreover, you have a test case that shows that it is wrong. Here's how to find the bug.

First, turn on all compiler warnings. There is no reason why a 20 line program should produce even a single warning. Warnings are the compiler telling you "this program compiles but does not do what you think it does", and since that is precisely the situation you are in, it behooves you to pay attention to those warnings.

Read them very carefully. If you don't understand why a warning is being produced, that's a good question for StackOverflow because it is a specific question about actual code. Be sure to post the exact text of the warning, the exact code that produces it, and the exact version of the compiler you're using.

If your program still has a bug, obtain a rubber duck. Or if a rubber duck is unavailable, get another computer science undergraduate, it's much the same. Explain to the duck using simple words why each line of each method in your program is obviously correct. At some point you will be unable to do so, either because you don't understand the method you wrote, or because it's wrong, or both. Concentrate your efforts on that method; that's probably where the bug is. Seriously, rubber duck debugging works. And as legendary programmer Raymond Chen points out in a comment below, if you can't explain to the duck why you're executing a particular statement, maybe that's because you started programming before you had a plan of attack.

Once your program compiles cleanly and the duck doesn't raise any major objections, if there's still a bug then see if you can break your code up into smaller methods, each of which does exactly one logical operation. A common error amongst all programmers, not just beginners, is to make methods that try to do multiple things and do them poorly. Smaller methods are easier to understand and therefore easier for both you and the duck to see the bugs.

While you're refactoring your methods into smaller methods, take a minute to write a technical specification for each method. Even if it is just a sentence or two, having a specification helps. The technical specification describes what the method does, what legal inputs are, what expected outputs are, what error cases are, and so on. Often by writing a specification you'll realize that you forgot to handle a particular case in a method, and that's the bug.

If you've still got a bug then first double check that your specifications contain all the preconditions and postconditions of every method. A precondition is a thing that has to be true before a method body can work correctly. A postcondition is a thing that has to be true when a method has completed its work. For example, a precondition might be "this argument is a valid non-null pointer" or "the linked list passed in has at least two nodes", or "this argument is a positive integer", or whatever. A postcondition might be "the linked list has exactly one fewer item in it than it had on entry", or "a certain portion of the array is now sorted", or whatever. A method that has a precondition violated indicates a bug in the caller. A method that has a postcondition violated even when all its preconditions are met indicates a bug in the method. Often by stating your preconditions and postconditions, again, you'll notice a case that you forgot in the method.

If you've still got a bug then learn how to write assertions that verify your preconditions and postconditions. An assertion is like a comment that tells you when a condition is violated; a violated condition is almost always a bug. In C# you can say using System.Diagnostics; at the top of your program and then Debug.Assert(value != null); or whatever. Every language has a mechanism for assertions; get someone to teach you how to use them in your language. Put the precondition assertions at the top of the method body and the postconditions before the method returns. (Note that this is easiest to do if every method has a single point of return.) Now when you run your program, if an assertion fires you will be alerted to the nature of the problem, and it won't be so hard to debug.

Now write test cases for each method that verify that it is behaving correctly. Test each part independently until you have confidence in it. Test a lot of simple cases; if your method sorts lists, try the empty list, a list with one item, two items, three items that are all the same, three items that are in backwards order, and a few long lists. Odds are good that your bug will show up in a simple case, which makes it easier to analyze.

Finally, if your program still has a bug, write down on a piece of paper the exact action you expect the program to take on every line of the program for the broken case. Your program is only twenty lines long. You should be able to write down everything that it does. Now step through the code using a debugger, examining every variable at every step of the way, and line for line verify what the program does against your list. If it does anything that's not on your list then either your list has a mistake, in which case you didn't understand what the program does, or your program has a mistake, in which case you coded it wrong. Fix the thing that is wrong. If you don't know how to fix it, at least now you have a specific technical question you can ask on StackOverflow! Either way, iterate on this process until the description of the proper execution of the program and the actual execution of the program match.

While you are running the code in the debugger I encourage you to listen to small doubts. Most programmers have a natural bias to believe their program works as expected, but you are debugging it because that assumption is wrong! Very often I've been debugging a problem and seen out of the corner of my eye the little highlight show up in Visual Studio that means "a memory location was just modified", and I know that memory location has nothing to do with my problem. So then why was it modified? Don't ignore those nagging doubts; study the odd behaviour until you understand why it is either correct or incorrect.

If this sounds like a lot of work, that's because it is. If you can't do these techniques on twenty line programs that you wrote yourself you are unlikely to be able to use them on two million line programs written by someone else, but that's the problem that developers in industry have to solve every day. Start practicing!

And the next time you write an assignment, write the specification, test cases, preconditions, postconditions and assertions for a method before you write the body of the method! You are much less likely to have a bug, and if you do have a bug, you are much more likely to be able to find it quickly.

This methodology will not find every bug in every program, but it is highly effective for the sort of short programs that beginner programmers are assigned as homework. These techniques then scale up to finding bugs in non-trivial programs.

4
  • 3
    Acho que fica melhor separar o texto traduzido (sem o original e com o link) em uma resposta.
    – rray Mod
    Commented 10/07/2018 às 13:43
  • Só vale observar que existe a possibilidade de que esse texto fique no limbo ou que o blog pode ser desativado. O artigo já tem quatro anos e o autor não posta nada há mais de um. Commented 10/07/2018 às 13:52
  • @rray "Acho que fica melhor separar o texto traduzido" - Feito!
    – hkotsubo
    Commented 10/07/2018 às 13:56
  • @LeandroAngelo Creio que este é um problema que já existe hoje, pois a página do MCVE possui um link para o artigo original, e se o blog for desativado, esta página ficará desatualizada. Traduzindo o texto e deixando aqui no meta, esse problema é minimizado, pois pelo menos teremos o conteúdo em português. E de qualquer forma, me comprometi a enviar o link da tradução para o autor, para que ele fique ciente da existência do mesmo. Mas entendo a sua preocupação...
    – hkotsubo
    Commented 10/07/2018 às 13:59

1 Resposta 1

17

Segue uma proposta de tradução. Procurei não fazer algo literal, por isso tem algumas adaptações no texto. Também não traduzi alguns termos como "debugar" e "assertions", mas fiquem à vontade para opinar e sugerir mudanças na tradução.


Como debugar programas pequenos

Este artigo é uma tradução de How to debug small programs, escrito por Eric Lippert.

Um dos tipos mais comuns de perguntas ruins que aparecem no Stack Overflow é:

Eu escrevi esse programa, mas não funciona. [20 linhas de código].

E só.

Se você está lendo isso, provavelmente é porque alguém te passou este link em uma pergunta que você fez no Stack Overflow, um pouco antes dela ser negativada e fechada (se você está lendo isso e não se encaixa neste caso, pode deixar suas dicas para debugar programas pequenos nos comentários, ou adicionando uma resposta).

Stack Overflow é um site de perguntas e respostas para questões específicas sobre código. "Eu escrevi um código com bugs e não consigo resolver" não é uma pergunta, é uma história, e sequer é uma história interessante. "Por que quando subtraio um de zero obtenho um número maior que zero, fazendo minha comparação com zero na linha 12 retornar true incorretamente?" é uma pergunta específica sobre código.

Então você está pedindo que a Internet faça o debug de um programa que você escreveu. Provavelmente nunca te ensinaram a debugar um programa pequeno, pois vou te contar uma coisa, este não é um jeito eficiente de resolver o seu problema. Hoje é um bom dia para aprender a debugar sozinho, porque o Stack Overflow não é um site feito para debugar os seus programas para você.

Vou assumir que o seu programa compila mas não faz o que deveria, e além disso, você tem um caso de teste que mostra que ele está errado. Vejamos como encontrar o bug.

Primeiro, ligue todos os avisos do compilador (compiler warnings). Não há motivo para um programa de 20 linhas produzir um warning que seja. Warnings são o compilador te dizendo "este programa compila mas não faz o que você acha que faz.", e como esta é exatamente a situação na qual você se encontra, cabe a você prestar atenção a estas mensagens.

Leia as mensagens cuidadosamente. Se você não entende por que um warning está aparecendo, esta é uma boa pergunta para o Stack Overflow pois é uma pergunta específica sobre código. Certifique-se de colocar a mensagem exata do warning, o código exato que a produz, e a versão exata do compilador que você está usando.

Se o seu programa ainda tem um bug, arranje um pato de borracha. Caso você não tenha um pato de borracha, arranje um aluno de ciência da computação, é quase a mesma coisa. Explique para o pato, usando palavras simples, porque cada linha de cada método do seu programa está obviamente certa. Em algum ponto você será incapaz de fazê-lo, seja porque você não entende o método que escreveu, ou porque ele está errado, ou ambos. Concentre seus esforços neste método; é provável que o bug esteja ali. Sério, debugar com um pato de borracha funciona. Como o lendário programador Raymond Chen disse certa vez, se você não consegue explicar para o pato porque está executando determinado comando, talvez seja porque você começou a programar antes de ter uma estratégia.

Se o seu programa compila e o pato não tem mais nenhuma objeção, mas ainda existe um bug, você pode quebrar seu código em métodos menores, com cada um contendo uma única operação lógica. Um erro comum entre muitos programadores, não apenas iniciantes, é criar métodos que tentam fazer muitas coisas e não as fazem da melhor maneira. Métodos menores são mais fáceis de entender, e consequentemente mais fáceis para você e o pato encontrarem os bugs.

Enquanto você estiver refatorando seu código em métodos menores, gaste um minuto para escrever a especificação técnica de cada método. Mesmo que seja apenas uma ou duas frases, ter uma especificação ajuda. A especificação técnica descreve o que o método faz, quais as entradas válidas, quais são as saídas esperadas, os casos de erro, etc. Muitas vezes, ao escrever a especificação, você perceberá que esqueceu de tratar algum caso particular, e esse é o bug.

Se o seu programa ainda tem um bug, verifique se as especificações contêm todas as pré-condições e pós-condições de cada método. Pré-condição é algo que deve ser verdadeiro antes da chamada do método, para que ele funcione. Pós-condição é algo que deve ser verdadeiro depois que o método terminou seu trabalho. Por exemplo, uma pré-condição poderia ser "este parâmetro deve ser um ponteiro não-nulo", ou "a lista deve ter pelo menos dois elementos", ou "este parâmetro deve ser um número positivo", ou qualquer outra coisa. Uma pós-condição pode ser "a lista possui exatamente um elemento a menos do que tinha no início", ou "o array está ordenado", etc. Um método que tem uma pré-condição violada indica um bug em quem está chamando este método. Um método que tem uma pós-condição violada quando todas as pré-condições estão satisfeitas indica um bug no próprio método. Geralmente, ao definir as pré-condições e pós-condições, você notará um caso que esqueceu de tratar no método.

Se o seu programa ainda tem um bug, aprenda a escrever assertions que verifiquem as pré-condições e pós-condições. Um assertion é como um comentário que diz se determinada condição foi violada; uma condição violada quase sempre é um bug. Em C# você pode colocar using System.Diagnostics; no topo do seu programa e então fazer Debug.Assert(value != null); por exemplo. Toda linguagem tem um mecanismo de assertions; encontre alguém para ensiná-lo a usar na sua linguagem. Coloque os assertions das pré-condições no início do método e das pós-condições antes do seu retorno (isso é mais fácil se o método só possui um único ponto de retorno). Agora quando você rodar o programa, se um assertion falhar você será alertado sobre o problema, e não será tão difícil debugar.

Agora escreva casos de teste para cada método, para verificar se o seu comportamento está correto. Teste cada parte de forma independente até você ter confiança nela. Teste vários casos simples; se o seu método ordena uma lista, tente com uma lista vazia, com apenas um elemento, com dois elementos, três elementos iguais, três elementos em ordem inversa, e algumas listas maiores. Há grande chance do seu bug aparecer em casos simples, o que o torna mais fácil de analisar.

Por fim, se o seu programa ainda tem um bug, escreva em um papel o que exatamente você espera que cada linha do programa faça para o caso que não funciona. Seu programa só tem 20 linhas. Você deve ser capaz de escrever tudo que ele faz. Agora rode o seu programa usando um debugger, examinando cada variável em cada passo, e a cada linha verifique se o programa faz o mesmo que está na sua lista. Se ele fizer algo que não está na sua lista, então a sua lista tem um erro, e nesse caso você não entendeu o que o programa faz, ou o programa tem um erro, e nesse caso você escreveu o código errado. Conserte o que estiver errado. Se você não sabe consertar, pelo menos agora você tem uma pergunta técnica que pode ser feita no Stack Overflow! De qualquer maneira, repita este processo até que a descrição sobre a execução do programa seja igual à execução de fato.

Enquanto você roda o código no debugger, eu te aconselho a prestar atenção às pequenas dúvidas. Muitos programadores têm a tendência natural de acreditar que seus programas funcionam da forma esperada, mas se você está debugando, é porque esta premissa é falsa! Em várias vezes eu estava debugando um problema e via com o canto do olho aquele pequeno aviso do Visual Studio dizendo que "o endereço de memória foi modificado", e eu sabia que o endereço de memória não tinha nada a ver com o meu problema. Mas então por que ele foi modificado? Não ignore estas pequenas dúvidas; estude o comportamento estranho até que você entenda porque ele está certo ou errado.

Se isso parece muito trabalho, é porque é mesmo. Se você não conseguir aplicar estas técnicas em um programa de 20 linhas que você mesmo escreveu, provavelmente não vai conseguir usá-las em programas de milhões de linhas escritos por outras pessoas, mas este é um problema que desenvolvedores precisam resolver todos os dias. Comece a praticar!

E da próxima vez que você escrever um programa, escreva a especificação, casos de teste, pré-condições, pós-condições e assertions de cada método antes de escrever o código do método! Isso diminui as chances de ter um bug, e mesmo que tenha, você terá mais chances de encontrá-lo rapidamente.

Este método não encontrará todos os bugs de todos os programas, mas é muito eficiente para o tipo de programas pequenos que programadores iniciantes recebem como exercício. Por fim, estas técnicas podem escalar para encontrar bugs em programas não triviais.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .