Como escrever mensagens de erro úteis

Apresentação para encontro de Python em Floripa

Transcript

1. Como escrever mensagens de erro úteis Elias Dorneles @eliasdorneles
2. EMPATIA Valor básico em desenvolvimento de software
3. Por que é importante se colocar no lugar do usuário?
4. É legal ter um designer projetando as interações com o usuário final, inclusive as mensagens de erro
5. A melhor mensagem de erro é nenhuma Se você sabe o que devia fazer, não tente “educar”: just do it! $ python Python 2.7.6 (default, Jun 22 2015, 17:58:13) [GCC 4.8.2] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> exit Use exit() or Ctrl-D (i.e. EOF) to exit >>> UGH! Não use a atenção do usuário desnecessariamente.
6. Às vezes é simplesmente uma questão de tentar de novo https://pypi.python.org/pypi/retrying
7. Dê feedback o mais cedo possível
8. Exemplo: verificando presença de argumentos def verifica_argumentos(args, obrigatorios): """Verifica se argumentos obrigatorios estao presentes no dicionario de argumentos """
9. Exemplo: verificando presença de argumentos def verifica_argumentos(args, obrigatorios): """Verifica se argumentos obrigatorios estao presentes no dicionario de argumentos """ for nome_arg in obrigatorios: if nome_arg not in args: raise ValueError("Argumento obrigatorio: %s" % nome_arg)
10. Exemplo: verificando presença de argumentos >>> obrigatorios = ('nome', 'idade', 'cpf') >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios) ... ValueError: Argumento obrigatorio: idade
11. Exemplo: verificando presença de argumentos >>> obrigatorios = ('nome', 'idade', 'cpf') >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios) ... ValueError: Argumento obrigatorio: idade >>> verifica_argumentos({'nome': 'Elias', 'idade': 99}, obrigatorios) ... ValueError: Argumento obrigatorio: cpf UGH!
12. Dê feedback o mais cedo e o mais completo possível
13. Exemplo: verificando presença de argumentos def verifica_argumentos(args, obrigatorios): """Verifica se argumentos obrigatorios estao presentes no dicionario de argumentos """ faltando = set(obrigatorios) - set(args) if faltando: msg = "Faltando argumentos: %s" % ', '.join(faltando) raise ValueError(msg)
14. Exemplo: verificando presença de argumentos >>> obrigatorios = ('nome', 'idade', 'cpf') >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios) ... ValueError: Faltando argumentos: idade, cpf
15. Exemplo: verificando presença de argumentos >>> obrigatorios = ('nome', 'idade', 'cpf') >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios) ... ValueError: Faltando argumentos: idade, cpf >>> verifica_argumentos({'nome': 'Elias', 'idade': 99, 'cpf': '007'}, obrigatorios) >>>
16. Mesmo princípio em outras situações • Checar espaço disponível antes de copiar/descompactar arquivos • Validar campos num formulário à medida que vão sendo preenchidos • Usar asserções que cobrem o máximo possível nos testes de unidade (ex: assertItemsEqual() )
17. “Se você bater nessa placa, você vai bater naquela ponte”
18. As pessoas em geral não leem mensagens de erro Não é burrice: é atenção limitada. Elas têm mais o que fazer do que pegar seu programa pela mão. ;-)
19. Use um texto curto.
20. Use um texto curto. Mas não obscuro.
21. Exemplo: enviando notificação def notifica_produto_disponivel(produto): try: NotificationService.send(type='product_is_available', id=produto.id) except: print("Deu erro enviando product_is_available") WAT?
22. Evite usar nomes de coisas internas do código
23. Dê o contexto, informe de verdade
24. Exemplo: enviando notificação def notifica_produto_disponivel(produto): try: NotificationService.send(type='product_is_available', id=produto.id) except Exception as e: print("Erro ao notificar que produto %s esta disponivel: %s" % (produto, e))
25. Exemplo: enviando notificação import logging def notifica_produto_disponivel(produto): try: NotificationService.send(type='product_is_available', id=produto.id) except Exception as e: msg = ("Erro ao notificar que produto %s esta disponivel: %s" % (produto, e)) logging.error(msg)
26. Diga o que fazer para resolver o problema
27. Exemplo: def publica_app(app_id): try: deploy_application(app_id) return {'status': 'ok'} except ServiceUnavailable: message = ("O serviço está indisponível no momento." " Tente de novo em alguns minutos.") return {'status': 'error', 'message': message}
28. Outro exemplo: def send_email(email): try: EmailService.send(email) return {'status': 'ok'} except UserQuotaExceededError: message = ("You reached the limit for your current plan." " Upgrade plan at: http://example.com/upgrade") return {'status': 'error', 'message': message}
29. Mantenha profissionalismo Usuários confusos ou frustrados não estão se divertindo. Não faça piadinhas.
30. Resumindo: 1. Resolva o problema automaticamente, se possível 2. Aponte problemas cedo 3. Seja breve, mas informe o contexto completo 4. Indique como resolver o problema 5. Mantenha profissionalismo -- sem piadas
31. Obrigado! Perguntas? Elias Dorneles http://twitter.com/eliasdorneles Referências: • http://www.ihearttechnicalwriting. com/write-error-messages/ • http://uiwriting.tumblr. com/post/128339130079/4-things-to- improve-ui-writing • http://www.nngroup.com/articles/error- message-guidelines/ • https://developer.gnome.org/hig- book/unstable/language-errors.html.en • http://bugroll.com/how-to-write-good- error-messages.html