Escrever software é dificil. Manter um software atualizado e em funcionamento
sem defeitos, é ainda mais dificil.

Uma das ferramentas mais importantes para que isso ocorra, isto é, a criação
e manutenção de um bom software, com o mínimo de defeitos (nenhum software é perfeito), é sem dúvida, os relatórios de
defeitos, ou bug reports.

Eles podem ser criados por qualquer pessoa que use de fato o software, qualquer
que ele seja. Alguns relatórios de bugs (chamaremos apenas de bugs, daqui por)
diante serão escritos por desenvolvedores, que notarão comportamentos estranhos
ainda na etapa de desenvolvimento. Outros serão escritos por testadores profissionais,
que ganham o pão procurando a desgraça alheia. E outros bugs, serão encontrados
apenas quando o nosso software estiver em produção - pelo usuário final.

Não importando quem escreveu, todo e qualquer bug merece um relatório e uma
investigação formal. O quanto antes, melhor. Bugs tendem a ficar cada vez mais
caros, conforme o tempo passa. Estima-se que um bug descoberto em produção custa 10 vezes mais o valor do que se ele tivesse sido encontrado antes - durante o desenvolvimento.

A conta é simples: se o bug tivesse sido encontrado durante a etapa de desenvolvimento, o desenvolvedor gastaria 2 horas para resolvê-lo e adicionar
um teste de unidade, afim de garantir que o mesmo não retorne para assombrar ninguém,
anos depois.

Se o bug é encontrado em produção, serão gastos, aproximadamente, 20 horas para
resolvê-lo. Senão mais. Tudo em produção é mais difícil.

Certo, bugs são caros, mas e daí? Bem, se podemos resolver o bug em desenvolvimento
e uma das principais formas de se resolver um bug é criando um bug report,
bons relatórios de bugs facilitam a vida dos desenvolvedores, na hora de encontrar
o danado e resolvê-lo de uma vez por todas.

Maus relatórios de bugs deixarão os desenvolvedores e usuários irritados. Bugs
com títulos e descrições inadequadas serão muito mais difíceis de serem resolvidos,
pois são mais difíceis de serem encontrados, terem o comportamento exato reproduzido,
assim por diante.

Uma máxima importante é:

Um bom relatório de bug descreve o problema de forma que o desenvolvedor familiarizado com o projeto pode entender e resolvê-lo, sem falar com a pessoa que o escreveu.

Esta é uma tradução generalizada de uma [postagem do martiancraft][martincraft-bug-report]. Realmente, devo concordar com o título.

Pequena estória: uma certa vez, trabalhando com um cliente - sem expertise técnica, decidiu que gostaria de escrever seus próprios relatórios de bugs. Ótimo, pensei, uma coisa a menos que terei de fazer. Este cliente nunca havia utilizado ou mesmo visto um relatório de bug.

Quando ele começou a escrevê-los, ele colocava títulos estranhos, descrições que não mencionavam como reproduzir o mesmo e tentava explicar problemas de desenho da tela, utilizando palavras - sem um simples screenshot se quer. Tudo bem, pensei, ele apenas precisa aprender a escrever melhores relatórios de erros e nossa vida será muito mais fácil. Enviei alguns links para ele e a situação melhorou.

Os bugs eram corrigidos mais rapidamente, pois gastávamos menos tempo tentando entender o que ele quis dizer com aquilo. Facilitou a comunicação sobre outras funcionalidades que ele queria para seu produto. Entre diversas outras coisas.

Então, confiem em mim: um bom relatório de erros é essencial para a vida do desenvolvedor e do maior interessado, o cliente.

Então, o que todo bom relatório de bugs deve conter?

Apenas um problema por relatório

Apenas um problema por relatório de defeito. Apenas. Um. Problema. Por. Relatório.

Não existe forma de deixar isto mais claro. Quando você tem um ou mais defeitos em um mesmo relatório de bugs, isto confunde o desenvolvedor, dificulta a correção e dificulta principalmente o teste da correção.

Outra: os dois problemas andam juntos, são corrigidos juntos e aprovados juntos. Em uma equipe, estes problemas poderiam ter sido resolvidos em paralelo, fechados com timelines distintas (um bug era fácil, o outro difícil) e com maior qualidade.

Nunca reporte mais de um bug em um único relatório. Nunca. Mesmo se eles forem relacionados. Cada bug é importante o suficiente para merecer seu próprio relatório.

Título e Descrição

Um bom título é essencial para avaliação rápida do problema. Títulos que não esclarem a situação, ou mascaram o problema real, são as formas erradas de começar a escrever um relatório de erros.

Um bom título ajuda o desenvolvedor a realizar a triagem do bug, algo como: "ah é só um texto na tela", "faltou uma validação aqui e ali" e "rapaz...tenho menor ideia do que diabos é isso". Não só ajuda a identificar a criticidade do bug, mas também mais ou menos de onde vem o problema, facilitando a delegação da resolução para um ou outro desenvolvedor ou time.

Já as descrições são os lugares para se dar detalhes sobre o bug. Contexto, informações do ambiente, passos para reprodução do bug, dados para reprodução do bug, temperatura do ar, pressão atmosférica e humor do chefe no dia.

Sem essas informações cruciais, fica muito mais difícil reproduzir o bug, tornando o mais caro para a empresa e para o cliente.

Exemplos:

  • RUIM: "A aplicação não responde";
  • BOM: "A aplicação não responde após a carga do arquivo XPTO na tela FOO";

  • RUIM: "Texto fora do padrão";

  • BOM: "Texto do título 'Pesquisa' está desformatado";

  • RUIM: "Não consigo salvar imagens";

  • BOM: "Dentro da tela de redimensionar imagens, ao tentar salvar a mesma após cortar 30% da largura da imagem, não consigo salvar as imagens";

Acho que deu para entender.

Passos detalhados e comportamento esperado

Certo, temos nossos bugs, mas como recriar a situação? A primeira coisa que um desenvolvedor fará, é tentar recriar a situação para ver se o erro encontrado não é esporádico, se tem relação com as marés ou a lua, ou se é realmente um defeito encontrado consistentemente.

Defeitos esporádicos, como, "relatório não pode ser gerado durante os meses que possuem 31 dias" existem e são legítimos, mas o desenvolvedor primeiro irá procurar se ele não vem de uma má configuração ou algum passo errado que o usuário possa ter executado no momento de usar a aplicação.
Defeitos consistentes são rapidamente avaliados pois temos certeza de quais passos realizar para reproduzir o erro. Sem os passos, o desenvolvedor deverá contar com a sorte para reproduzir o danado - tarefa tediosa e que pode não resolver o problema.

Vamos dizer que um erro é encontrado em apenas 1/10 das vezes em que se executam uma tarefa, aleatoriamente. O desenvolvedor testou 9 vezes, mas o erro não se apresentou. O que ele irá pensar? Que não existe erro algum e talvez o usuário estivesse em uma versão antiga, ou o conjunto de dados mudou.

Mesmo que o responsável por reportar o defeito não saiba exatamente quais ações foram realizadas, em detalhes, para incluir no relatório, um conjunto mínimo de passos ajuda muito.

Exemplo:

  • RUIM: "Loguei no sistema e cliquei em imprimir no relatório.";
  • BOM:
    • Logar no sistema com usuário que tenha permissão para gerar relatórios;
    • Clicar na seção de relatórios;
    • Escolher o relatório de faturamento;
    • Agrupar por mês e filial;
    • Clicar em gerar relatório;
    • Sistema apresenta uma tela azul;
    • Sistema deveria apresentar uma tela com um relatório em PDF, contendo o relatório de faturamento mensal, agrupado por filial;

A diferença entre os dois é gritante.

Quanto ao comportamento esperado, ele também é fundamental para quem for testar o bug e confirmar que o mesmo está resolvido. Além dos passos de testes, o comportamento esperado é o prego no caixão do defunto - ele tratá a certeza para o desenvolvedor de que o problema morreu.

Contexto

Informações de contexto são cada vez mais importantes, conforme os mesmos são distribuídos por uma gama muito maior de clientes - a web, por exemplo.

Um bom contexto contém:

  • Sistema operacional e versão;
  • Navegador utilizado e versão (em aplicações web);
  • Versão do software que está sendo utilizado;
  • Informações relevantes ao uso do sistema (dados, usuários, grupos e permissões, etc);
  • Condições especiais (com GPS do celular ligado, com pouca bateria no notebook, com a rede ligada, etc);

Em casos extremos, como aplicações gráficas ou desktops, qual placa de vídeo, qual resolução utilizada, etc. Quanto maior o número de detalhes, mais fácil.

Prioridade

Não confunda prioridade com criticidade. Prioridade é o quanto um bug impacta no dia a dia do usuário. Um bug crítico em uma funcionalidade usada apenas uma vez no ano, é muito importante, mas um bug de severidade média em uma ferramenta utilizada todos os dias tem prioridade muito maior de resolução.

Screenshots

Ah, os screenshots. Eles são muito úteis para provar que o usuário não está louco sonhando. Brincadeiras à parte, os screenshots colocam o desenvolvedor numa máquina do tempo e na máquina do usuário. Principalmente se o bug envolver qualquer tipo de tela ou interface de usuário.

Não é tão difícil, então, sempre que possível, tire um screenshot, desenhe em cima dele, aponte uma seta para o problema. O desenvolvedor será muito grato.

Quando fechar um bug

Existe ciclo de vida natural de um bug, que varia de empresa para empresa, mas o mais simples geralmente acontece assim:

  1. Defeito é encontrado;
  2. Bug é relatado;
  3. Desenvolvedor faz uma triagem do bug;
  4. Desenvolvedor resolve o bug;
  5. Desenvolvedor altera o status do bug para o relator conferir se o problema realmente foi resolvido;
  6. Relator fecha o bug (ou reabre, caso o conserto não tenha sido muito bom - neste caso, volte para item 3);

Este é o fluxo mínimo que temos de trabalho. Quando o bug resolvido chegar na "mesa" do relator, ele deve separar um tempo para fazer o teste da resolução, o quanto antes melhor e dar andamento nos processos.

Se outro defeito foi encontrado, crie outro bug. A maior parte das ferramentas atuais permitem que você referencie bugs e/ou tarefas, facilitando o desenvolvedor a acompanhar o histórico.

Pensamentos finais

Escrever relatórios de erros não é difícil. É um processo em que se colabora com a construção do software, então deve ser minimamente organizado e coerente. Desenvolvedores não tem bolas de cristal e não são hackers do tipo Matrix, onde vem tudo em código o tempo todo.

Um bom relatório de bugs é certamente apreciado e muito mais legal de ser resolvido do que um mau relatório. Seja bonzinho e nos ajude a te ajudar :D.

Links interessantes