$30 off During Our Annual Pro Sale. View Details »

Como escrever mensagens de erro úteis

Como escrever mensagens de erro úteis

Apresentação para encontro de Python em Floripa

Elias Dorneles

November 04, 2015
Tweet

More Decks by Elias Dorneles

Other Decks in Programming

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