9 Boas Práticas para reportar Erros de Software

A maioria dos developers tem uma relação de amor / ódio com o reportar erros de software. Eles adoram relatórios de erros porque estes são cruciais para obter feedback de software testers e utilizadores sobre formas como podem melhorar uma aplicação. Mas eles odeiam-nos porque, bem, responder a relatórios de erros não está propriamente no topo da lista de como passar um bom bocado para os developers.

Isso é especialmente verdade quando eles têm de lidar com relatórios de erros redundantes, mal escritos, difíceis de seguir ou problemáticos. Esses relatórios tendem a receber a menor prioridade e podem irritar tanto os developers que optam por não responder a qualquer problema ou problemas que os relatórios contenham.
É por isso que, se desejas que o teu relatório de erros receba a atenção que merece, é fundamental prepará-lo bem. De seguida são apresentadas nove práticas recomendadas para um relatório de erros de software, sejas tu um engenheiro que reporta erros para a sua própria equipa ou um utilizador final externo, que vai preencher um relatório de erros sobre o software que usa.

1. Identifique o problema de forma clara e específica

Em primeiro lugar e acima de tudo, os seus relatórios de erros de software devem identificar clara e especificamente qualquer problema que esteja a procurar comunicar aos programadores.

Poder-se-ia pensar que isto seria escusado dizer. Mas é fácil cair na armadilha de escrever um relatório de erros de software que não é suficientemente específico sobre o que está realmente errado, porque descreve a questão em termos demasiado genéricos.

Por exemplo, um relatório que diz que há uma “degradação no desempenho” sob certas condições não é muito específico. Seria melhor dizer exactamente como é que o desempenho se degrada: Será que a interface deixa de responder? Há um atraso notável na aplicação quando se trata de pedidos que envolvem a rede? Será que a aplicação consome mais recursos do sistema?

Outra forma de pensar sobre como identificar claramente a questão é escrever o que se esperava que acontecesse e depois descrever o que realmente aconteceu. “Esperava que a interface continuasse a responder, mas ficou sem resposta e cinzenta depois de ter clicado no botão verde Start” identifica claramente o que está errado.

2. Cingir-se a um problema por relatório de erro de software

Outra boa e básica prática para a comunicação de erros de software é manter um problema por relatório. Se estiver a ter múltiplos problemas com uma aplicação – como um lançamento inicial lento e uma interface atrasada uma vez que a aplicação esteja em execução – relate cada problema separadamente.

Isto pode parecer intuitivo o suficiente. Mas onde as pessoas muitas vezes erram é quando assumem que os diferentes problemas que estão a experimentar estão relacionados e devem, portanto, ser reportados como um único erro.

Na realidade, dois problemas aparentemente semelhantes podem ou não estar ligados. Se estão ou não ligados, esta é uma decisão a ser tomada pelos programadores à medida que investigam e resolvem os problemas. Se os programadores decidirem mais tarde que dois problemas estão relacionados, podem fundir os relatórios de erros em conformidade. Deixe isso ao critério deles.

3. Não sugerir uma causa ou correção para o erro

Quando apresenta um relatório de erros de software, pode ter as suas suspeitas sobre o que pensa ser a causa do problema. Talvez suspeite que está relacionado com uma certa biblioteca de software ou que foi causado por uma actualização específica, por exemplo.

Pode pensar que oferecer tais sugestões aos programadores dentro do relatório irá ajudá-los a resolver o problema mais rapidamente. Mas o facto é que normalmente é melhor deixar que os programadores descubram o que se está a passar, sem os empurrar em certas direcções. Isto permite uma resposta mais objectiva, ao mesmo tempo que evita a necessidade dos programadores anotarem no relatório porque é que a sua sugestão de correção não é a correção correcta.

A exceção é se já tiver explorado a questão por si próprio e extraído resultados conclusivos sobre a causa. Se testou diferentes versões da aplicação sob as mesmas condições exactas e determinou que o problema ocorre apenas com uma versão, por exemplo, é digno de nota. Mas dizer simplesmente que o problema começou a ocorrer após uma recente actualização da aplicação, sem provas conclusivas que demonstrem que a actualização está relacionada com o problema, não é muito útil.

4. Certifique-se de que o erro continua a ocorrer

Por vezes, o que se pensa ser um erro real numa aplicação, revela-se uma falha temporária que foi causada por uma condição rara e temporária no seu ambiente. Estas questões são geralmente difíceis de duplicar (o que as torna difíceis de investigar e corrigir) e não são suficientemente comuns para merecerem sérios esforços de remediação por parte dos criadores.

Uma regra geral para evitar desperdiçar o tempo dos programadores em relatórios sobre questões raras e pontuais é certificar-se de que o problema que pretende relatar ocorre pelo menos três vezes antes de apresentar um relatório. Caso contrário, se não o conseguir duplicar de forma consistente no seu próprio sistema, é pouco provável que os programadores consigam desencadear o erro de uma forma que lhes permita compreendê-lo e resolvê-lo.

5. Evitar a gíria técnica

A comunicação de erros de software pode parecer um lugar onde a gíria técnica será bem-vinda. De facto, pode até pensar que os programadores esperam que utilize linguagem técnica, porque é assim que estão habituados a comunicar uns com os outros.

No entanto, a menos que esteja a reportar um erro para a sua própria equipa e tenha a certeza de quais os termos técnicos que eles irão e não irão reconhecer, é melhor manter o português simples. Diga, por exemplo “Depois de uma nova instância do processo XYZ ter começado, a interface deixou de responder, depois a aplicação falhou, e finalmente todo o sistema operativo ficou sem resposta até eu reiniciar o computador”.

6. Mantenha o relatório de erros breve e mantenha-se fiel aos factos

Poderá pensar que quanto mais informação partilhar no processo de comunicação de erros de software, mais fácil será para os programadores responderem. Na realidade, os programadores que têm dezenas ou mesmo centenas de relatórios para classificar querem que cada um deles seja curto, doce e directo ao assunto.

Inclua dados relevantes, como informação sobre versões de aplicações e sistemas operativos. Mas evite narrativas estranhas, como, “instalei esta aplicação pela primeira vez há duas semanas, e até ontem funcionou muito bem. Depois, hoje, depois de ter aberto um e-mail, começou a agir de forma estranha”.

7. Incluir a saída da linha de comando (command-line output), se possível

Algumas aplicações podem ser executadas tanto na linha de comando como utilizando interfaces gráficas. Em geral, obterá muito mais dados de resolução de problemas num command-line output (CLI) do que a partir de uma interface gráfica (GUI).

Portanto, se a sua aplicação tiver uma versão CLI, não se esqueça de tentar executar essa versão para ver se experiencia o mesmo problema que quando utiliza uma GUI. Se não, então sabe que o problema está limitado à GUI. Se assim for, provavelmente obterá mais informações do CLI que poderá partilhar no seu relatório de erros.

8. Não confundir pedidos de características com relatórios de erros

Por vezes, os utilizadores que apresentam relatórios de erros não estão de facto a comunicar um erro. Estão a solicitar uma nova funcionalidade ou um melhoramento da aplicação.

Alguns programadores utilizam os mesmos sistemas de rastreio de erros e pedidos de características, mas tratam diferentes tipos de registos para cada um, e os utilizadores têm de saber o que estão a pedir quando apresentam o relatório ou pedido inicial. Outros utilizam sistemas totalmente diferentes para pedidos de características, e alguns podem não ter um sistema formal de pedido de características; em vez disso, podem esperar que se inicie uma discussão na sua lista de email.

Seja qual for o caso, certifique-se de que, se quiser partilhar as suas ideias para uma nova funcionalidade com os programadores, utilize o caminho certo e evite preencher um relatório de erros para algo que não seja um erro.

9. Permanecer disponível após o envio

O melhor relatório de erros tem pouca utilidade se a pessoa que o escreveu desaparece depois de o ter apresentado. É muito comum os programadores solicitarem informações adicionais à pessoa que reportou o erro, pelo que permanecer disponível depois de ter apresentado o relatório é tão importante como apresentar um bom relatório em primeiro lugar.

Conclusão

Quando se trata de relatórios de erros de software, seguir as melhores práticas para escrever relatórios claros, concisos e focados ajudará os programadores do seu software a gostar muito mais dos seus relatórios. Por sua vez, desfrutará de uma resolução mais rápida de quaisquer problemas que enfrente na utilização do software, para não mencionar uma melhor reputação entre os programadores.

O artigo original, escrito por Christopher Tozzi, foi publicado no ITPro Today, pode ser lido aqui: https://www.itprotoday.com/development-techniques-and-management/9-best-practices-software-bug-reporting