What makes a good error message (or API return code) ?

Yet another example just now of what must rank as a textbook example of the worst kind of error message - "Invalid Parameter":

https://devzone.nordicsemi.com/f/nordic-q-a/52898/error-0x000000007-invalid-parameter-in-advertising_init/213360#213360

The message is unhelpful in that it neither tells you which parameter was invalid, nor how it was invalid.

It is even worse in this particular case, because it can also happen when the parameters are each individually valid, but the particular combination is not allowed. 

So fixing the problem becomes a game of trial-and-error.

So what makes for a good error message?

(and in that, I'm including API return codes)

The key thing is that it must not just tell that something is wrong - it must give you sufficient information to know what was wrong, why it was wrong and, thus,  how to fix it!

In the case of the API return codes here, that probably means that one single code is not enough - there will need to be a number of codes, each describing a specific error.

Parents
No Data
Reply
  • A great error message would be as you described, telling you what is wrong, where it went wrong (be that code line or register address), which system was affected and how to fix it.

    I guess the issue is that for developers of Libraries and Compilers is that they have to assume a level of skill and coding knowledge on behalf of the user. For a skilled programmer, a simple error message or error code return value is sufficient to isolate the issue *most* of the time. For people such as myself who are fresh out of University and are still learning however, sometimes it's not so obvious.

    I remember issues with Socket maniplation that would return error codes that were outside the values listed in error code list for sockets leaving me clueless in what the error issue even was for a while. So a little more information would be appreciated in most instances. 

    I do think that in some instances, not all errors need huge detail. Sometimes just a friendly reminder and a point to the code is all that is needed for most programmers with basic level coding skills to understand, such as "expected ';' ", there's no need to explain much there. 

    With regards to error values, I think that having error values that can be linked back to well defined error conditions is extremely helpful, from a learning standpoint as well as a code fixing standpoint, but I do think that again the developers have to assume there is some knowledge of the subject in the users. Otherwise they would need to list every possible user error issue or hardware issue under the sun to create a list that had all the desired information we are talking about.

Children
  • A great error message would be as you described, telling you what is wrong, where it went wrong (be that code line or register address), which system was affected and how to fix it.

    I don't think it's necessarily the place of the error message to tell you how to fix the problem (that may not even be possible) - but it should certainly give all the information that you need in order to work out the solution.

    With regards to error values, I think that having error values that can be linked back to well defined error conditions is extremely helpful

    My point is that it's not just "helpful" - a "nice to have" - it is essential.

    It is the very point of having status returns.

    Otherwise, it might just as well be a boolean success/fail.