Let's talk about errors and warnings.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
- sliptonic
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Let's talk about errors and warnings.
I've noticed that there isn't much consistency in how we're using FreeCAD.Console.PrintWarning and FreeCAD.Console.PrintError.
The result is a mess of red and orange messages in the report view.
In my opinion, the user would ideally never see a red message (error). When red messages appear, the developers should be studying that situation and making the code more robust. For example, if an operation can't calculate a toolpath because the user didn't select any geometry, it isn't an error. In fact, the program operated exactly as designed and the toolpath is empty. Of course, the program should give a warning or other helpful information but it shouldn't confuse a user mistake with a program error.
But I want your feedback. Should we be using error messages to teach the user how to use the program?
The result is a mess of red and orange messages in the report view.
In my opinion, the user would ideally never see a red message (error). When red messages appear, the developers should be studying that situation and making the code more robust. For example, if an operation can't calculate a toolpath because the user didn't select any geometry, it isn't an error. In fact, the program operated exactly as designed and the toolpath is empty. Of course, the program should give a warning or other helpful information but it shouldn't confuse a user mistake with a program error.
But I want your feedback. Should we be using error messages to teach the user how to use the program?
- dubstar-04
- Posts: 698
- Joined: Mon Mar 04, 2013 8:41 pm
- Location: Chester, UK
- Contact:
Re: Let's talk about errors and warnings.
I agree that we need to be more consistent with use of logging, however i'm not sure what the correct use is.
I have been using it like a traffic light type system where:
Green = No message, all is as expected
Yellow = Warning: Potentially an issue that needs the users attention
Red = Error: The user needs to correct something before the code can return a result.
I am happy to go over any portions of the code and change if required.
Thanks,
Dan
I have been using it like a traffic light type system where:
Green = No message, all is as expected
Yellow = Warning: Potentially an issue that needs the users attention
Red = Error: The user needs to correct something before the code can return a result.
I am happy to go over any portions of the code and change if required.
Thanks,
Dan
Last edited by dubstar-04 on Tue May 26, 2020 2:29 pm, edited 1 time in total.
Re: Let's talk about errors and warnings.
No, not at all. I had started a similar discussion quite some time ago, because I had the feeling that during the second half of 0.19 the number of errors have made a leap forward.
It wouldn't really be a problem, but the messages one should care about can currently well be buried under a heap of other messages.
In my view an error in Report view means
- it should be reported here in the forum
- or it has been reported here
What really annoys me are error messages in the regular workflow: everything works as expected, but nevertheless an error is raised. We see this e.g. in the following places:
- Entering pocket without something selected: "Please select faces from a single solid".
This is normal workflow, because the faces can well be selected later. It may be discussed if an error should be raised if the operation is finally confirmed and no face has been selected.
- Facing operation behaves the same: unwanted error on entering without selection, no error on confirmation
- Adaptive clearing op behaves the same: unwanted error on entering without selection, no error on confirmation
- Deburr op behaves the same on entering: unwanted error without selection (confirmation without selection raises an error which is ok)
- entering Profile/Contour without face selected: This is worse than the previous operations, because for Contour nothing should be selected.
Outside of Path we have similar or even worse messages, which cannot be avoided at all:
Loft: No possibility to avoid the error message on creation - extremely annoying.
Sweep: No possibility to avoid the error message on creation - extremely annoying.
CheckGeometry: If an error is detected, the error is shown in report view as well. This is wrong, because CheckGeometry works as designed.
In Path all operations write a warning on entering and leaving. We are now far beyond the prototype state, so these messages should be completely removed.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
- sliptonic
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Re: Let's talk about errors and warnings.
Chris, in those cases mentioned where it's normal workflow, should the errors just be changed to warnings or should the system remain entirely silent?
I've started a cleanup branch and most of the offending code is my own old stuff.
I've started a cleanup branch and most of the offending code is my own old stuff.
Re: Let's talk about errors and warnings.
I tend to agree with this paradigm, and disagree a bit with chrisb. In my opinion, the error should be raised whenever a tool or command cannot proceed due to some cause. It does not have to be a catastrophic error that needs to be reported on the forum, it just has to be something that stops the user from proceeding. So in this case, yes, we should instruct the user the proper workflow with certain messages.dubstar-04 wrote: ↑Mon May 25, 2020 5:43 pm Green = No message, all is as expected
Yellow = Warning: Potentially an issue that needs the users attention
Red = Error: The user needs to correct something before the code can return a result.
Code: Select all
provide_number("514")
error: the function requires a number, not a string
Code: Select all
calculate_something(123)
warning: this function will be removed in the future
Say that there are three fields, for length, height, and depth, but the user only enters one value. On pressing OK, the interface should print "error: missing height and depth". So, the program should not proceed with incomplete information. Once the user has all values, the command should simply execute and not report anything, or if anything, just an OK message, "tool: number calculated successfully".
Now, I don't use Path a lot, so I don't have much experience on how verbose it is. In Draft, I like to print a message when a function completes, just to give feedback on what the user actually created. But this is a normal message, not a warning nor error.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Let's talk about errors and warnings.
No warnings in normal workflow. They have the meaning as defined by dubstar: "be alert!". I would not even like to see them as normal messages.
I understand very well, why they are there. It is quite normal in the development process. Now Path is mature enough to clear itself from its eggshells.I've started a cleanup branch and most of the offending code is my own old stuff.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
Re: Let's talk about errors and warnings.
So as a compromise to allow power users to see what's going on but not annoy the majority, if I change the output from Error to Log that means it's still easy to copy and paste for those who need it?
https://github.com/FreeCAD/FreeCAD/blob ... y.cpp#L705
&
https://github.com/FreeCAD/FreeCAD/blob ... y.cpp#L738
Re: Let's talk about errors and warnings.
I have the feeling it's still a compromise, but a very good one!
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
- sliptonic
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Re: Let's talk about errors and warnings.
I agree with Chris. Less is sometimes more. The default condition when Path is operating normally should be silence. Developers should use the PathLog module more to put informational messages in so a curious user can see more output if desired.
Red in report view should ONLY be used if something unexpected happens. Let's make a clear distinction between a program error and a user mistake.
The OCL based operations (surface/waterline) test if OCL is installed and throw an error if not. In my opinion, this should still be an error. Change my mind.
Red in report view should ONLY be used if something unexpected happens. Let's make a clear distinction between a program error and a user mistake.
The OCL based operations (surface/waterline) test if OCL is installed and throw an error if not. In my opinion, this should still be an error. Change my mind.
Re: Let's talk about errors and warnings.
Last edited by Syres on Wed May 27, 2020 10:05 am, edited 1 time in total.