Conventions for the amount of detail to post Python exception messages?

Question

I am trying to identify some guidelines for writing exception messages.

For example, suppose a hypothetical function that should receive a constant number of bytes (as a bytes object), and we call it using [1, 2, 3] . All possible exceptions are listed below:

 1. TypeError 2. TypeError: argument must be 16 bytes 3. TypeError: argument must be 16 bytes; got 'list' 4. TypeError: argument must be 16 bytes; got 'list' [1, 2, 3] 

As a rule, I feel that the message should always explain a condition that has not been met, but I am concerned about how much information needs to be included in the abusive object.

Are there any recommendations on this?

Answer 1

Great question!

When I generally create custom exceptions, I usually look at the Python set, which is usually exhaustive.

Now that I have asked how detailed it is, I would not have made them too specific, because you do not know what will cause them or cause.

In the example:

 TypeError: unsupported operand type(s) for +: 'int' and 'str' 

Descriptive enough to report that the + operator is not supported, I don't need to know what the string contains.

So, in your example, the first two are absolutely beautiful, and secondly, they overwhelm IMO.

Good luck.

Answer 2

I don't have many references to the “installed idiom” to give you, but here are my 2 ¢:

Your goal is to have a bad juice that breaks the exception (that is, maybe not you and / or far in the future) to have enough information to understand the problem and hopefully fix it.

Information is transmitted through exceptions in several ways:

• Stack Trace - You will get it for free.
• Type of exception. There is some art of choosing the right type and deciding when it is advisable to create your own more specific type of exception.
• The message is the part you are asking for.

You should also consider:

• Context. How is this exception intended to be used? Is this a critical error when you want to get the most information, or is it a temporary condition that customers may want to process in their code, and debugging information is not so important? If your exception is likely to be handled by client-side code, you probably want to put your information in a machine-readable format rather than a text message. For example, enter an error code enumeration field.

But as a rule, I think it’s better to ask myself: “If I got this exception in production code, what information do I need for me?”

Personally, in the example you give, I would choose option (4) every time. I do not think too much information. Your exception looks like it should never happen, and if that happens, you want to know exactly what went wrong.

If you do not take into account the information, as in (1-3), you provide the possibility of confusion in what is actually happening.

Do not provide unnecessary information in messages - do not be detailed just for the sake of it. But give all relevant information in favor of a future maintainer who is scratching his head.