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
   

   View Slide

2. EMPATIA
   Valor básico em desenvolvimento de software
   

   View Slide

3. Por que é importante se colocar no lugar do usuário?
   

   View Slide

4. É legal ter um designer projetando
   as interações com o usuário final,
   inclusive as mensagens de erro
   

   View Slide

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.
   

   View Slide

6. Às vezes é simplesmente
   uma questão de tentar de novo
   https://pypi.python.org/pypi/retrying
   

   View Slide

7. Dê feedback o mais cedo possível
   

   View Slide

8. Exemplo: verificando presença de argumentos
   def verifica_argumentos(args, obrigatorios):
   """Verifica se argumentos obrigatorios estao
   presentes no dicionario de argumentos
   """
   

   View Slide

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)
   

   View Slide

10. Exemplo: verificando presença de argumentos
    >>> obrigatorios = ('nome', 'idade', 'cpf')
    >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios)
    ...
    ValueError: Argumento obrigatorio: idade
    

    View Slide

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!
    

    View Slide

12. Dê feedback o mais cedo
    e o mais completo possível
    

    View Slide

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)
    

    View Slide

14. Exemplo: verificando presença de argumentos
    >>> obrigatorios = ('nome', 'idade', 'cpf')
    >>> verifica_argumentos({'nome': 'Elias'}, obrigatorios)
    ...
    ValueError: Faltando argumentos: idade, cpf
    

    View Slide

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)
    >>>
    

    View Slide

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()
    )
    

    View Slide

17. “Se você bater nessa placa, você vai bater naquela ponte”
    

    View Slide

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. ;-)
    

    View Slide

19. Use um texto curto.
    

    View Slide

20. Use um texto curto.
    Mas não obscuro.
    

    View Slide

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?
    

    View Slide

22. Evite usar nomes
    de coisas internas do código
    

    View Slide

23. Dê o contexto,
    informe de verdade
    

    View Slide

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))
    

    View Slide

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)
    

    View Slide

26. Diga o que fazer para resolver o problema
    

    View Slide

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}
    

    View Slide

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}
    

    View Slide

29. Mantenha profissionalismo
    Usuários
    confusos ou
    frustrados não
    estão se
    divertindo.
    Não faça
    piadinhas.
    

    View Slide

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
    

    View Slide

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
    

    View Slide