issues: 256557897

This data as json

id node_id number title user state locked assignee milestone comments created_at updated_at closed_at author_association active_lock_reason draft pull_request body reactions performed_via_github_app state_reason repo type
256557897 MDU6SXNzdWUyNTY1NTc4OTc= 1566 When reporting errors, note what value was invalid and why 12229877 closed 0     3 2017-09-11T01:25:44Z 2019-08-19T06:50:15Z 2019-08-19T06:50:15Z CONTRIBUTOR      

I've regularly had to debug problems with unusual or slightly broken data - or my misunderstanding of various layers of the software stack -, and I can't be the only one. For example:

  • open_mfdataset tries to open an invalid file. Which file? Why is it invalid?
    (one was truncated when the download crashed - I had to find it by size)
  • Xarray can't convert a dtype. What dtype couldn't it convert? And of what variable? (it was a boolean mask)

And of course there are many more examples. This manifesto has some good advice, but in essence:

  • Think about the information a new user will need to understand what has gone wrong and fix their code. It's good to be verbose here, because new users need this information most and experienced users won't see it anyway (or might be glad it's there on occasion!).
  • Report:
  • The value that was invalid (or a summary that rules out validity; eg shape and dtype for arrays)
  • The operation that was attempted
  • Why the value was invalid in this operation
  • If possible, what the user can do to fix this

This is quite an open-ended issue; as well as the code changes it probably requires some process changes to ensure that new errors are equally helpful. Ultimately, the goal is for errors to become a positive aid to learning rather than a frustrating barrier.

 
{
    "url": "https://api.github.com/repos/pydata/xarray/issues/1566/reactions",
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   completed 13221727 issue

Links from other tables