Join GitHub today
Better errors with codes and `hoa explain` #51
Hello fellow @hoaproject/hoackers and users!
As a direct or indirect user of Hoa, I want better errors than a simple exception backtrace. I want more context about errors.
Rust and Elm errors are exemplaries. For instance in Rust:
Or in Elm:
We must provide a better mechanism to understand errors thrown by Hoa libraries. This RFC takes inspiration from the Rust and Elm languages.
Majority of the time spent on a new project consists of dealing with errors. This RFC will:
So far, Hoa does not trigger any error. Only exceptions are thrown. Each exception is uniquely indexed per class (so 0, 1, 2, 3 for class
Index is stored in the
By errors, we mean exceptions. An error code is defined by a specific format. In Rust, an error format has the following form:
We can use the
Given an error code, we can get more explanations about what leads to it, how to avoid it etc. The new
The description would include this:
The format of the description will be markdown.
The “Invalid example” and “Valid example” Sections must be strictly named like this. They act as “anchors” for error-based testing, see bellow. All sections can contain zero or more code blocks.
It will be easy to collect all errors, and publish them online. This will be a good resource for everyone, and it will publicly show we are serious regarding errors.
Obviously, these error descriptions must be testable. We can extract the code from the examples, compile them to integration test cases, and then run them. All the example code blocks in the “Invalid example” Section are expected to fail. All the example code blocks in the “Valid example” Section are expected to succeed.
What command to run to test the errors? Maybe
Too much errors to manage?
If you think we have too much errors to manage, then this would be because we have too much errors at all. In this case, we must reduce the amount of errors a library can produce. If the number goes too high, it means we might be doing something wrong. This is a good probe.
Location of error descriptions
Just like we have
Print exception message
When printing the exception message, instead of printing the exception index as usual, we print:
sprintf( '%s%03d', file_get_contents('hoa://Library/Acl/Documentation/Error/Prefix.txt'), $exception->getCode() )
or, if we store the whole error code in
What do you think? To be frank, majority of the time I spend on a new project is not coding but dealing with stupid errors. This mechanism will help a lot any new comers.
referenced this issue
Feb 27, 2017
I like the idea of have a normalized makdown template, related to error code.
And i've commonly end up to use
Can you give us a detail about
It does not conflict. We can have nice exception types, and nice codes too. Exception types (sub-classes of
Hmm yes. I understand the need to have a severity attribute on exception, but I would not use
Simply indexing exceptions like 1, 2, 4 for
Good question. What happens if an exception has no code? Well, we won't tell the user to use
Ok we are on same line, but, look at Hoa Exception today.
This is why i'm asking, do we need to refactor our Exception by strictly specify a error code ?
as an example, if a method who throws an exception expects to receive an array of strings but receives a number instead, we should throw
Can we share code between library ?
Yesterday evening, we talked about this RFC during the Hoa Virtual meeting.
In Hoa, each exception already exists for a specific need and already have a solid meaning. Relying on exception types instead of creating code may be more relevant.
Now, with Kitab, we can add all the documentation above the class declaration with examples. This examples will be tested to be sure the documentation is always valid.
If you look at angular js 1, all error come with a link inside the js console to the website of angular. And the website of angular display an explanation on this error. For me like shulard say, Hoa is very specific in his exception, so just with the exception name we could redirect to a website with explanation, overall with kitab.
All that stuff can be added directly into the documentation.
This is OK to cancel an RFC if we have a single tool that addresses several problems or needs. This is actually even better!