Let's talk about errors and warnings.

[sliptonic]

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?

[dubstar-04]

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

[chrisb]

But I want your feedback. Should we be using error messages to teach the user how to use the program?

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.

[sliptonic]

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.

[vocx]

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 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.

Code: Select all

provide_number("514")

error: the function requires a number, not a string

A warning is something that the user should note, but doesn't stop the execution right now.

Code: Select all

calculate_something(123)

warning: this function will be removed in the future

Now, notice that this mostly refers to the programming interface from Python. A graphical tool, a button that you click and that launches a task panel, should already do a lot of error handling internally so that the user can only input correct values. I think sensible defaults should be provided in case the user doesn't add all the information that is required. But still, if the user doesn't provide necessary values, I think a message is still required to inform the user about the proper workflow.

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.

[chrisb]

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?

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've started a cleanup branch and most of the offending code is my own old stuff.

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.

[Syres]

CheckGeometry: If an error is detected, the error is shown in report view as well. This is wrong, because CheckGeometry works as designed.

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

[chrisb]

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?

I have the feeling it's still a compromise, but a very good one!

[sliptonic]

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.

[Syres]

I have the feeling it's still a compromise, but a very good one!

PR Submitted https://github.com/FreeCAD/FreeCAD/pull/3516

Edit: PR number updated