Por Simon Tatham, profissional e programador de software livre
Qualquer um que já tenha escrito software para uso público provavelmente recebeu pelo menos um relatório de bugs mal feito. Relatórios que não dizem nada ("Não está funcionando!"), relatórios que não fazem sentido, relatórios que não dão informação suficiente, relatórios que dão informações erradas, relatórios de problemas que acabam resultando de um erro do usuário, relatórios de problemas que acabam sendo resultado do erro de programas de terceiros, e relatórios de erros que se revelam na verdade falhas de rede.
Há uma razão para a qual suporte técnico seja visto como um trabalho horrível, e a razão são os relatórios de bugs errados. Entretanto, nem todos os relatórios de bugs são desagradáveis: eu mantenho softwares livres, quando não estou ganhando a vida, e às vezes recebo relatórios de bugs claros, úteis e informativos.
Neste ensaio vou tentar clarificar como se faz um bom relatório de bugs. Idealmente eu gostaria que todo mundo lesse este enasio antes de relatar qualquer bug para qualquer outro programador. Certamente eu gostaria que todo mundo que reportasse bugs para mim o lesse.
Em resumo, o objetivo de um relatório de bug é permitir que o programador veja o programa falhando na sua frente. Você pode mostrar isto pessoalmente, ou dar instruções cuidadosas e detalhadas sobre como fazer o programa falhar. Se ele consegue repetir a falha, ele vai tentar obter informações extra até que saiba a causa. Se ele não conseguir repetir a falha, ele irá pedir a você que obtenha esta informação para ele.
Em relatórios de bugs, tente tornar bem claro quais são os fatos ("eu estava no computador e aconteceu isto") e o que é especulação ("eu acho que o problema pode ser este"). Deixe de fora as especulações se você quiser, mas não deixe de fora os fatos.
Quando estiver relatando um bug, você o está fazendo por que quer ver o mesmo corrigido. Não há lucro em xingar o programador ou ser deliberadamente pouco cooperativo: pode ser um erro deles e um problema para você, e você pode ter o direito de estar furioso com eles, mas o bug será corrigido mais raídamente se você ajudá-los, fornecendo toda informação que precisarem. Lembre-se que o programa também é gratuito, e o autor o está fornecendo por bondade, e se muitas pessoas são rudes com ele então ele pode parar de ser bonzinho.
Dê algum crédito à inteligência básica do programador: se o programa realmente não funcionasse, ele provavelmente teria percebido. Como ele não percebeu, é por que provavelmente deve estar funcionando para ele. Portanto, ou você está fazendo algo diferente, ou seu ambiente é diferente do dele. Ele precisa de informação, fornecer esta informação é o objetivo de um relatório de bugs. Muita informação é sempre melhor que pouca.
Muitos programadores, particularmente os de software livre, publicam sua própria lista de bugs. Se você puder encontrar uma lista de bugs conhecidos, vale a pena ler a mesma para ver se o bug que você encontrou já não é conhecido. Se ele já é conhecido, provavelmente não vale a pena reportar o mesmo novamente, mas se você pensa ter mais informações que o relatório na lista de bugs, você pode querer contatar o programador mesmo assim. Ele poderá corrigir o bug mais facilmente se você der a ele informações que ele ainda não tem.
Este ensaio está cheio de diretrizes. Nenhuma é uma regra absoluta. Diferentes programadores etm diferentes formas que eles gostariam de ver os bugs serem reportados. Se o programa vem com seu próprio conjunto de diretrizes para relatórios de bugs, leia elas. Se as diretrizes que acompanham o programa contradizem as deste ensaio, siga as que acompanham o programa!
Se você não está relatando um bug, mas pedindo por ajuda para usar o programa, informe onde você já procurou respostas para sua questão ("eu olhei o capítulo 4 e a seção 5.2 mas não consigo encontrar nada que me diga se isto é possível"). Isto fará com que o programador saiba onde os usuários esperam encontrar a resposta, de forma que possam fazer a documentação mais fácil de usar.
Uma das melhores formas de relatar um bug é mostrando o mesmo ao programador. Vá ao computador, inicie o programa, e demonstre a coisa que está errada. Deixe-o ver você iniciar sua máquina, observar você iniciar o programa, observar como você interage com o programa, e ver o que o software faz em resposta a tuas entradas.
Ele conhece o software como a palma da mão. Sabe em que partes ele pode confiar, e sabe quais partes podem ter problemas. Intuitivamente ele sabe o que observar. No momento que o software fizer algo obviamente errada, ele pode ter notado algum erro sutil um pouco antes que possa lhe dar uma pista. Ele pode observar tudo que o computador faz durante o teste, e podem separar as informações relevantes eles mesmos.
Isto pode não ser suficiente. Ele pode decidir que precisa de mais informações, e pedir que você mostre a mesma coisa novamente. Ele pode pedir que você fale sobre o procedimento, de forma que possa reproduzir o bug ele mesmo quantas vezes ele quiser. Ele pode tentar mudar um pouco o procedimento e ver se o problema ocorre somente em um caso ou em uma família de casos relacionados. Se você não tiver sorte, ele pode precisar sentar por algumas horas com um conjunto de ferramentas de desenvolvimento e realmente iniciar investigações. Mas a coisa mais importante é ter um programador olhando o computador quando algo dá errado. Uma vez que ele veja o problema ocorrendo, ele pode começar a partir daí e tentar corrigir o bug.
Esta é a era da Internet. A era da comunicação mundial. Esta é a era em que eu posso enviar meu software para alguém na Rússia com o toque de um botão, e ele pode me enviar os comentários sobre o mesmo com a mesma facilidade. Mas se ele tem um problema com meu programa, ele não pode contar comigo para olhar o programa falhar. "Mostre-me" é bom quando você pode, mas geralmente você não pode mostrar.
Se você tem que relatar um bug a um programador que não pode estar presente, o objetivo do exercício é possibilitar que ele possa reproduzir o problema. Você quer que o programador execute sua própria cópia do programa, faça as mesmas coisas, e que a falha ocorra da mesma forma. Quando ele puder ver o problema acontecendo, ele pode lidar com o mesmo.
Conte ao programador exatamente o que você fez. Se é um programa gráfico, diga quais botões você apertou e em que ordem você os apertou. Se é um programa que você executou escrevendo uma linha de comando, mostre precisamente qual comando você escreveu. Onde for possível, forneça uma transcrição da sessão, mostrando quais comandos você escreveu e qual a resposta do computador.
Dê ao programador toda invormação que você puder lembrar. Se o programa lê dados de um arquivo, provavelmente você vai precisar enviar uma cópia do arquivo. Se o computador troca informações com outro computador na rede, você provavelmente não vai poder mandar uma cópia daquele computador, mas pode dizer que tipo de computador é e (se você puder) qual software está sendo rodado no mesmo.
Se você der ao programador uma lista longa de entradas e ações, e ele iniciar sua própria cópia do programa e não ocorrer o erro, então você não forneceu informações suficiente. Possivelmente a falha não aparece em todos computadores, seu sistema e o do programador podem ser diferentes de alguma forma. Possivelmente você tenha entendido errado o que o programa deveria fazer, e vocês estão olhando exatamente para a mesma informação mas você pensa que está errado e o programador pensa que está certo.
Por isto, descreva também o que aconteceu. Diga exatamente o que você vê. Diga por quê você pensa que está errado, ou melhor, diga exatamente o quê você esperava ver. Se você disser "então ficou tudo errado", você deixou de fora algumas informações muito importantes.
Se você ver mensagens de erro, diga ao programador, cuidadosa e precisamente, quais são estas mensagens. Elas são importantes. Neste estágio, o programador não está tentando corrigir o problema: ele está tentando encontrar o mesmo. Ele precisa saber o que deu errado, e as mensagens de erro são o melhor esforço do computador para dizer isto. Escreva os erros se você naõ tem outra forma fácil de lembrar os mesmos, mas não é de ajuda erlatar que o programa gerou um erro a menos que você possa relatar qual a mensagem de erro.
Em particular, se a mensagem de erro possui números, informe ao programador este número. Só por que você não vê sentido algum no mesmo não significa que não há nenhum. Os números contém todo tipo de informação que pode ser lida por programadores, e eles provavelmente contém pistas vitais. Números em mensagens de erro estão lá por que o computador está muito confuso para colocar o erro em palavras, mas está fazendo o seu melhor para dar informações importantes para você mesmo assim.
Neste estágio, o programador está fazendo serviço de detetive. Ele não sabe o que aconteceu, e não consegue chegar perto o suficiente para ver o erro acontecer por si mesmo, por isto estão procurando por pistas que podem levar o mesmo adiante. Mensagens de erro, strings incompreensíveis de números, e mesmo demoras não explicadas são todas tão importantes quanto digitais na cena de um crime. Guarde-as!
Se você está usando Unix, o programa pode ter produzido um core dump. Core dumps são uma boa fonte de pistas, por isto não os apague. Por outro lado, muitos programadores não gostam de receber enormes arquivos core via e-mail sem nenhum aviso, por isto pergunte antes de enviar um para alguém. Outra coisa, esteja ciente que arquivos core contém um registro completo do estado do programa: quaisquer "segredos" envolvidos (pode ser que o programa estava tratando uma mensagem pessoal, ou de dados confidenciais) podem estar dentro do arquivo core.
Existem muitas coisas que você pode fazer quando um erro ou bug acontece. Muitas tornam o problema pior. Uma amiga da escola apagou todos os seus documentos Word por engano, e antes de pedir ajuda para alguém experiente, ela tentou reinstalar o Word, e tentou rodar o Defrag. Nenhum destes procedimentos ajudaram a recuperar seus arquivos, e também alteraram o disco ao ponto que nenhum programa Undelete no mundo poderia recuperar qualquer coisa. Se ela não tivesse feito nada, pode ser que tivesse alguma chance.
Usuários como este são como uma fuinha encurralado: com as costas contra a parede e com a morte certa à frente, eles atacam frenéticamente, por que fazer qualquer coisa é melhor que não fazer nada. Este tipo de comportamento não é o mais apropriado para os problemas que os computadores produzem.
Não haja como uma fuinha, mas como um antílope. Quando um antílope é confrontado com algo inesperado ou assustador, ele pára. Ele fica absolutamente parado e tenta não chamar nenhuma atenção, enquanto pensa e faz o melhor que pode (se os antílopes tivessem suporte técnico, estariam telefonando para ele neste momento). Uma vez que tenham decidido qual a atitude mais segura, eles agem.
Quando algo dá errado, pare imediatamente de fazer qualquer coisa. Não aperte nenhum botão. Olhe a tela e veja tudo que não for normal, e memorize ou anote. Então talvez aperte cautelosamente "OK" ou "Cancelar", o que parecer mais seguro. Tente desenvolver uma reação reflexo - se um computador faz algo inesperado, pare.
Se você conseguir livrar-se do problema, quer fechando o programa afetado ou desligando o computador, uma coisa boa a se fazer é tentar repetir o erro. Os programadores gostam de problemas que possam reproduzir mais de uma vez. Programadores felizes corrigem bugs mais rapidamente e com mais eficiência.
Não são somente os não programadores que produzem maus relatórios de bugs. Alguns dos piores relatórios de bugs que eu já vi foram produzidos por programadores, e até mesmo de bons programadores.
Eu estava trabalhando com outro programador certa vez, que ficava encontrando bugs em seu próprio código e ficava tentando corrigir os mesmos. Toda vez que ele encontrava um bug que não conseguia resolver, ele me pedia ajuda. "O que está errado?" eu perguntava. Ele respondia dizendo sua opinião sobre o que precisava ser corrigido.
Este procedimento funcionava quando sua opinião estava correta. Signficava que ele tinha feito metade do trabalho e podia completar a tarefa comigo. Era eficiente e útil.
Mas frequentemente ele estava errado. Trabalhávamos então por algum tempo tentando descobrir por que um trecho em particular do programa estava produzindo dados incorretos, e eventualmente descobríamos que não era isto que estava acontecendo, que estávamos investigando uma parte correta do programa por meia hora, e que o problema estava em outra parte.
Tenho certeza que ele não faria isto a um médico. "Doutor, eu preciso de uma prescrição de Hydroyoyodyne." As pessoas sabem o que dizer a um médico: você descreve os sintomas, os desconfortos reais e dores e comichões e febres, e deixa para o médico fazer o diagnóstico sobre o problema e o que fazer a respeito. Senão o médico vai pensar que você é um hipocondríaco ou um maluco, e provavelmente está certo.
Acontece o mesmo com os programadores. Fornecer o teu próprio diagnóstico pode ser útil de vez em quando, mas sempre apresente os sintomas. O diagnóstico é um extra opcional, e não uma alternativa ao fornecimento dos sintomas. Da mesma forma, enviar uma modificação para corrigir o problema é uma adição útil a um relatório de bug, mas não é substituto para o mesmo.
Se um programador pede informações extra, não o faça esperar! Alguém submeteu um relatório de bug para mim certa vez, e eu pedi para que o mesmo tentasse um comando que eu sabia que não funcionaria. A razão era que eu queria saber qual de duas mensagens de erro diferentes o programa daria. Saber qual a mensagem de erro que eu obteria em retorno daria uma pista vital. Mas ele não fez isto - simplesmente mandou um email de volta dizendo "Não, isto não funciona." Eu levei algum tempo para persuadi-lo a fazer a tentativa.
Usar sua inteligência para ajudar o programador é legal. Mesmo se suas deduções estiverem erradas, o programador firacá grato por você ter pelo menos tentado tornar sua vida mais fácil. Mas sempre forneça um relatório dos sintomas também, ou você poderá tornar sua vida muito mais difícil.
Diga "falha intermitente" na cara de um programador e veja seu rosto ficar sombrio. Os problemas fáceis são os que a execução de uma seqüência simples de ações causa a ocorrência da falha. O programador pode então repetir aquelas ações sob condições de teste mais de perto e observar o que acontece com bastante detalhes. Muitos problemas simplesmente não funcionam deste jeito: há programas que falham uma vez por semana, ou uma vez na lua cheia, ou nunca falham quando você experimenta ele na frente do programador mas sempre falham quando você está com no limite de um cronograma.
Muitas falhas intermitentes não são realmente intermitentes. A maioria tem alguma lógica em algum lugar. Algumas ocorrem quando a máquina está com pouca memória livre, outras ocorrem quando outro programa tenta mofificar um arquivo crítico na hora errada, e algumas podem ocorrer somente na primeira metade de cada hora! (Eu vi um programa que fazia isto.)
Da mesma forma, se você pode reproduzir o bug mas o programador não o consegue, pode ser que o computador dele e o seu tem alguma diferença que está causando o problema. Eu tinha um programa certa vez cuja janela encaracolou em uma bolinha no canto superior esquerdo da tela, ficou lá e emburrou-se. Mas isto só acontecia em telas de resolução 800x600, funcionando bem no meu monitor 1024x768.
O programador vai querer saber qualquer coisa que você consiga descobrir sobre o problema. Tente em outra máquina, talvez. Tente duas ou três vezes e veja a freqüência com que ele falha. Se ocorrer algo errado quando você estiver fazendo algum trabalho sério mas não quando você estiver tentando fazer uma demonstração, pode ser que longas horas de execução ou arquivos grandes seja o que o faz falhar. Tente lembrar tantos detalhes quanto puder sobre o que você estava fazendo quando ocorreu a falha, e se você conseguir perceber algum padrão, mencione o mesmo. Qualquer coisa que você fornecer pode ser de ajuda. Mesmo que seja apenas algo probabilístico (tipo "ele tende a falhar mais vezes quando o Emacs está rodando"), pode ser que não forneça provas diretas sobre a causa do problema, mas pode ajudar o programador a reproduzir o mesmo.
Principalmente, o programador vai querer certificar-se se está lidando com uma falha intermitente ou uma falha específica da máquina. Ele pode querer saber muitas informações sobre seu computador, de forma que ele possa trabalhar nas diferenças para o computador dele. Muitos detalhes dependerão do programa em particular, mas uma coisa que você deve estar pronto a fornecer são os números de versão. O número de versão do programa, do sistema operacional e provavelmente o número de versão dos programas envolvidos no problema.
Escrever com clareza é essencial em um relatório de bugs. Se o programador não consegue entender o que você quer dizer, você poderia muito bem não ter dito nada.
Eu recebo relatórios de bugs de todo mundo. Muitos destes vem de pessoas que não falam inglês, e com muitas desculpas pela pobreza do seu inglês. Em geral, os relatórios de bugs com pedidos de desculpas pelo inglês são na verdade bastante claros e úteis. A maioria dos relatórios confusos vem de pessoas que falam inglês que assumem que eu irei entendê-los mesmo se não fizerem nenhum esforço para serem claros ou precisos.
Disclaimer: Eu nunca vi uma fuinha ou um antílope, minha zoologia pode estar errada.
Copyright © 1999 Simon Tatham.
Este documento é OpenContent
Você pode copiar e usar o text nos termos da OpenContent
Licence.
Por favor, envie qualquer comentário e crítica para anakin@pobox.com.