Improve Error Handling Documentation #950

cuihtlauac · 2023-02-23T17:56:40Z

General considerations on error handling
Predefined exceptions
Runtime crashes
Usage of the Option type

Discuss thread: https://discuss.ocaml.org/t/updating-the-error-handling-tutorial/12022

data/tutorials/lg_08_error_handling.md

ghost · 2023-03-01T16:30:30Z

data/tutorials/lg_08_error_handling.md

+exception Failure of string
+```
+
+* `Exit` terminates your program with a success status, which is 0 in Unices (they do error values)


"they do error values" is confusing here. Did you mean to mention that Unix-like systems have processes returning an exit value? Does this even matter in this tutorial?

In the first section, I describe encoding errors as special values, as done in C. Mainly to state explicitly it shouldn't be done in OCAml. The text between the parenthesis is not a strict requirement for this tutorial, however, I'm tempted to believe it has some relevance. But I'm open to discussion. I agree the text needs to be clarified.

data/tutorials/lg_08_error_handling.md

ghost · 2023-03-01T16:50:25Z

data/tutorials/lg_08_error_handling.md

+
+Properly handling errors is a complex matter. It is [cross-cutting
+concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all
+parts of an application and can't be isolated in dedicated module. In contrast


Suggested change

parts of an application and can't be isolated in dedicated module. In contrast

parts of an application and can't be isolated in a dedicated module. In contrast

ghost · 2023-03-01T16:50:36Z

data/tutorials/lg_08_error_handling.md

+Properly handling errors is a complex matter. It is [cross-cutting
+concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all
+parts of an application and can't be isolated in dedicated module. In contrast
+to several other main stream languages, OCaml provides several mechanisms to


Suggested change

to several other main stream languages, OCaml provides several mechanisms to

to several other mainstream languages, OCaml provides several mechanisms to

ghost · 2023-03-01T16:50:46Z

data/tutorials/lg_08_error_handling.md

+concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all
+parts of an application and can't be isolated in dedicated module. In contrast
+to several other main stream languages, OCaml provides several mechanisms to
+handled exceptional circumstances, all with good runtime performances and code


Suggested change

handled exceptional circumstances, all with good runtime performances and code

handle exceptional circumstances, all with good runtime performance and code

ghost · 2023-03-01T16:51:03Z

data/tutorials/lg_08_error_handling.md

+to several other main stream languages, OCaml provides several mechanisms to
+handled exceptional circumstances, all with good runtime performances and code
+understandability. Using them properly requires some initial learning and
+partice. Later, it always require some thinking, which is good since proper


Suggested change

partice. Later, it always require some thinking, which is good since proper

practice. Later, it always requires some thinking, which is good since proper

ghost · 2023-03-01T16:51:32Z

data/tutorials/lg_08_error_handling.md

+understandability. Using them properly requires some initial learning and
+partice. Later, it always require some thinking, which is good since proper
+management of errors shouldn't ever be overlooked. No error handling is better
+than the others, and is should be matter of adequacy to the context rather some


Suggested change

than the others, and is should be matter of adequacy to the context rather some

than the others, and is should be matter of adequacy to the context rather than

christinerose

Mostly grammar/syntax suggestions. A few verb tense and typo corrections.
I didn't go over the code itself yet (to see if there are any gaps for a relative newbie), but I will shortly if you'd like.

data/tutorials/lg_08_error_handling.md

christinerose · 2023-03-01T18:45:13Z

data/tutorials/lg_08_error_handling.md

 ```

-And you will get a stacktrace. Alternatively, you can call, from within the program,
+And you will get a stack trace. Alternatively, you can call, from within the program,


Suggested change

And you will get a stack trace. Alternatively, you can call, from within the program,

This will produce a stack trace. Alternatively, you can call, from within the program,

(if my suggestion is correct!)

christinerose · 2023-03-01T19:11:50Z

data/tutorials/lg_08_error_handling.md

+Here, it would be wrong to use `failwith` since it requires the compiler to be
+bugged or the system to be corrupted for second code path to be executed.
+Breakage of the language semantics qualifies as extraordinary circumstances, it
+is catastrophic.


Suggested change

Here, it would be wrong to use `failwith` since it requires the compiler to be

bugged or the system to be corrupted for second code path to be executed.

Breakage of the language semantics qualifies as extraordinary circumstances, it

is catastrophic.

Here, it wouldn't be beneficial to use `failwith` since it requires the compiler to be

bugged or the system to be corrupted for second code path to be executed.

Breakage of the language semantics qualifies as extraordinary circumstances; it

is catastrophic.

christinerose · 2023-03-01T19:12:12Z

data/tutorials/lg_08_error_handling.md

+# Concluding Remarks
+
+Properly handling errors is a complex matter. It is [cross-cutting
+concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all


Suggested change

concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all

concern](https://en.wikipedia.org/wiki/Cross-cutting_concern); it touches all

christinerose · 2023-03-01T19:12:33Z

data/tutorials/lg_08_error_handling.md

+to several other main stream languages, OCaml provides several mechanisms to
+handled exceptional circumstances, all with good runtime performances and code
+understandability. Using them properly requires some initial learning and
+partice. Later, it always require some thinking, which is good since proper


Suggested change

partice. Later, it always require some thinking, which is good since proper

pratice. Later, it always require some thinking, which is good since proper

christinerose · 2023-03-01T19:12:49Z

data/tutorials/lg_08_error_handling.md

+handled exceptional circumstances, all with good runtime performances and code
+understandability. Using them properly requires some initial learning and
+partice. Later, it always require some thinking, which is good since proper
+management of errors shouldn't ever be overlooked. No error handling is better


Suggested change

management of errors shouldn't ever be overlooked. No error handling is better

error management shouldn't ever be overlooked. No error handling is better

christinerose · 2023-03-01T19:13:06Z

data/tutorials/lg_08_error_handling.md

+understandability. Using them properly requires some initial learning and
+partice. Later, it always require some thinking, which is good since proper
+management of errors shouldn't ever be overlooked. No error handling is better
+than the others, and is should be matter of adequacy to the context rather some


Suggested change

than the others, and is should be matter of adequacy to the context rather some

than the others, and it should be matter of adequacy to the context rather some

cuihtlauac · 2023-03-02T07:19:09Z

Thanks, @christinerose for your suggestions, that's great. I've committed them all. Yes if you want to test the code, that be nice too.

data/tutorials/lg_08_error_handling.md

rikusilvola · 2023-03-02T07:48:32Z

data/tutorials/lg_08_error_handling.md

-Exceptions belong to the type `exn` (an extensible sum type):
+The biggest issue with exceptions is that they do not appear in types. One has
+to read the documentation to see that, indeed, `List.find` or `String.sub` are
+not total functions, and that they might fail by raising an exception.


Total functions? Could benefit from unwrapping.

Can you explain a little bit? I don't get what you mean

Sure thing!

Since the document is intended for newcomers, those might include people unfamiliar with functional programming terminology. I would propose either a quick sidenote or a link to a definition, preferably on our site instead of on some other language's docs.

The document on functional programming needs to be updated. I was planning to add that kind of text there. I'll link to it

Sounds like the right place.

data/tutorials/lg_08_error_handling.md

rikusilvola · 2023-03-02T14:54:29Z

Brilliant!
I especially appreciate the extensive coverage of bind in error handling.
Having the use of both the binding operators and the infix bind documented on ocaml.org will be beneficial for newcomers.
👍

cuihtlauac · 2023-03-02T15:22:34Z

Thanks, @rikusilvola. BTW, I considered adding some text on how to deal with permanent vs transient failures, à la SRE. Might make sense. I have vague memories of a Google documentation where code patterns where put in front of various kinds of failures, but I couldn't find it. Does not seem to be in the SRE book. Does it ring a bell to you?

christinerose

Approving in the case all my questions/comments are irrelevant! 😄

Several expressions don't run, and it's not clear to me if they're supposed to run/output, be combined with something else to try it, or if it's just examples/information. I've left notes on several of those, but I stopped about 2/3 through to reduce the noise, as indicated in the last question about it.

A few expressions were missing the ;; to get the output, and I found one or two output errors/discrepancies.

I hope all this is helpful! Let me know about the code questions, and I can review it again. 🙂

data/tutorials/lg_08_error_handling.md

christinerose · 2023-03-02T20:08:41Z

data/tutorials/lg_08_error_handling.md

- : int option = None
+# String.sub "Hello world!" 3 (-2);;
+Exception: Invalid_argument "String.sub / Bytes.sub".
+# let rec loop x = x :: loop x


Suggested change

# let rec loop x = x :: loop x

# let rec loop x = x :: loop x;;

data/tutorials/lg_08_error_handling.md

christinerose · 2023-03-02T20:12:47Z

data/tutorials/lg_08_error_handling.md

+And you will get a stack trace. Alternatively, you can call, from within the
+program,

 ```ocaml


Is the code li 160 - 191 examples of code the user will write themselves, or is it something the reader should be able to test when going through this doc?

Again, that's for reading only

data/tutorials/lg_08_error_handling.md

christinerose · 2023-03-02T20:26:08Z

data/tutorials/lg_08_error_handling.md

+      | Some host_len -> Some (String.sub fqdn 0 host_len)
+      | None -> if fqdn <> "" then Some fqdn else None
+    end
+  | None -> None


If I put the ;; at this end of this, I get this output val host_opt : string -> string option = <fun>

data/tutorials/lg_08_error_handling.md

cuihtlauac · 2023-03-03T07:31:25Z

Several expressions don't run, and it's not clear to me if they're supposed to run/output, be combined with something else to try it, or if it's just examples/information. I've left notes on several of those, but I stopped about 2/3 through to reduce the noise, as indicated in the last question about it.

Since this keeps-on being a pain, I believe we have a more profound issue with code samples. I've filed this issue on the matter: #961

Let me know if it captures the difficulties you have. Starting from that we can consider, workarounds, to ease your work now and longer-termed solutions.

christinerose · 2023-03-04T01:29:35Z

Several expressions don't run, and it's not clear to me if they're supposed to run/output, be combined with something else to try it, or if it's just examples/information. I've left notes on several of those, but I stopped about 2/3 through to reduce the noise, as indicated in the last question about it.

Since this keeps-on being a pain, I believe we have a more profound issue with code samples. I've filed this issue on the matter: #961

Let me know if it captures the difficulties you have. Starting from that we can consider, workarounds, to ease your work now and longer-termed solutions.

OMG! Thank you so much for making this PR. The comments that I already see are very validating that this could be done more clearly. I look forward to exploring the options with the team.

rikusilvola · 2023-03-06T08:37:54Z

Thanks, @rikusilvola. BTW, I considered adding some text on how to deal with permanent vs transient failures, à la SRE. Might make sense. I have vague memories of a Google documentation where code patterns where put in front of various kinds of failures, but I couldn't find it. Does not seem to be in the SRE book. Does it ring a bell to you?

Hi @cuihtlauac ! No, I don't remember that from Google, but Microsoft has some good guidelines for transient fault handling as well as patterns for error handling for resilient applications. Maybe that's what you remember?

cuihtlauac · 2023-03-06T09:38:43Z

Hi @cuihtlauac ! No, I don't remember that from Google, but Microsoft has some good guidelines for transient fault handling as well as patterns for error handling for resilient applications. Maybe that's what you remember?

It must be it. Do you have the link or do you have tips on how I could find it myself?

rikusilvola · 2023-03-06T09:44:50Z

Hi @cuihtlauac ! No, I don't remember that from Google, but Microsoft has some good guidelines for transient fault handling as well as patterns for error handling for resilient applications. Maybe that's what you remember?

It must be it. Do you have the link or do you have tips on how I could find it myself?

https://learn.microsoft.com/en-us/azure/architecture/best-practices/transient-faults
https://learn.microsoft.com/en-us/azure/architecture/framework/resiliency/app-design-error-handling

cuihtlauac · 2023-03-06T09:49:26Z

Thanks @rikusilvola. It's not what I had in mind. But it's great stuff! I'll see what I can do from there.

Zineb-Ada · 2023-04-26T13:42:52Z

Excellent work, I find it very well explained and the code examples are clearer and more detailed.

data/tutorials/lg_08_error_handling.md

Tchou · 2023-04-26T15:03:31Z

(I don't know if this is the right place to give general comments, I can also reply on the discuss post. Also sorry if the points below have been taken into account already).
First, it's great that this tutorial is getting an update! A few high level remarks:

Some things have no place in this tutorial, especially if it's aimed at beginners. I would remove the subsection about Obj.magic entirely, you don't even want to mention to beginners that this thing exists. Further, it has nothing to do with exceptions vs monadic style.
I would not give an example that Stack_overflow is an exception (hence that you can catch it, you shouldn't).
The sections about option and result are really nice
I would move the part about (let*) to a dedicated subsection and clearly advertise that this is still a language extension and, although unlikely, its behavior may evolve.
It seems unfair to point pros and cons of exceptions at the beginning of their presentation and not do the same for options/results (namely that it incurs the burden of checking/extracting the enclosed value at every step, which may require some boilerplate code). This could then be used to advocate the use of binding operators. I would also mention that it incurs boxing/unboxing values which may come with a runtime cost.
w.r.t to code examples, it's ok to give code that, in isolation, does not compile (e.g. because some value is not defined because it was defined three examples above) but syntactically incorrect code such as val Option.map : … will be confusing for beginners that will try to cut and paste it. Maybe in such case, not use a code formatting box but just some tt font ?

AshineFoster · 2023-04-27T02:26:51Z

The introduction tells the reader not to use special values for error handling but does not say why. I made a new sample intro that gives a small hint as to the problems with special values.

Error Handling

Ocaml handles errors in several ways. This document presents these different ways,
with the exception of effect handlers introduced in Ocaml 5.

Some languages (C, C++, etc.) returns 'special values' to tell the calling function
that there was an error. For example the C printf function returns a negative
value if it encounters an output error. This style of error handling dictates
the programmer to always be aware of the different 'special values' functions might
return and take full responsibility to carry out an appropriate action. Of course
programmers don't always check the return values with the result being billions
of dollars lost and thousands of persons inconvenienced in certain cases.

Ocaml has three alternative ways to deal with errors:

Exceptions

Option values

Result values.

These three options (:-)) enables an Ocaml program to handle errors in much safer
and more consistent ways compared to C's 'special values'.

cuihtlauac · 2023-04-27T06:52:23Z

Thanks, @Tchou, for the nice words, this helps. To me, both here and discuss are fine for general comments.

I would remove the subsection about Obj.magic entirely, you don't even want to mention to beginners that this thing exists. Further, it has nothing to do with exceptions vs monadic style.

I would not give an example that Stack_overflow is an exception

I believe the initial goal of the document was to address all exceptional circumstances; that's why I felt those topics were needed. However, I share your concerns. Maybe I should add some text saying this is mentioned for completeness but left unexplained. As a beginner, I preferred that over “being left in the dark”.

I would move the part about (let*) to a dedicated subsection and clearly advertise that this is still a language extension and, although unlikely, its behavior may evolve.

Agreed, will do

It seems unfair to point pros and cons of exceptions at the beginning of their presentation and not do the same for options/results (namely that it incurs the burden of checking/extracting the enclosed value at every step, which may require some boilerplate code). This could then be used to advocate the use of binding operators. I would also mention that it incurs boxing/unboxing values which may come with a runtime cost.

Agreed, will do.

w.r.t to code examples, it's ok to give code that, in isolation, does not compile (e.g. because some value is not defined because it was defined three examples above) but syntactically incorrect code such as val Option.map : … will be confusing for beginners that will try to cut and paste it. Maybe in such case, not use a code formatting box but just some tt font ?

There's an open issue on that matter: #961

Since this applies to several tutorials, we'll probably won't fix this in this document, in order to preserve formatting consistency. Hopefully, it will help solve the issue at once for all the documents.

Grammar fixes Co-authored-by: Christine Rose <[email protected]>

Co-authored-by: Miod Vallat <[email protected]>

Co-authored-by: Christine Rose <[email protected]>

…rror at 4bd8925

sabine

Just one remark.

In general, I think it's good to merge and improve incrementally from there on.

data/tutorials/lg_08_error_handling.md

…rror at 4bd8925

cuihtlauac requested a review from christinerose as a code owner February 23, 2023 17:56

cuihtlauac marked this pull request as draft February 23, 2023 17:56

cuihtlauac mentioned this pull request Feb 28, 2023

Documentation Update Plan #956

Open

18 tasks

cuihtlauac marked this pull request as ready for review March 1, 2023 16:22

ghost reviewed Mar 1, 2023

View reviewed changes

christinerose suggested changes Mar 1, 2023

View reviewed changes

ghost reviewed Mar 2, 2023

View reviewed changes

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

rikusilvola reviewed Mar 2, 2023

View reviewed changes

ghost approved these changes Mar 2, 2023

View reviewed changes

rikusilvola reviewed Mar 2, 2023

View reviewed changes

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

christinerose approved these changes Mar 2, 2023

View reviewed changes

cuihtlauac force-pushed the doc-error branch from e1e001a to 4810b31 Compare April 6, 2023 12:48

cuihtlauac pushed a commit that referenced this pull request Apr 26, 2023

Squash and Merge #950

67fd941

cuihtlauac pushed a commit that referenced this pull request Apr 26, 2023

Squash and Merge #950

6ec3c9f

ghost reviewed Apr 26, 2023

View reviewed changes

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

cuihtlauac pushed a commit that referenced this pull request Apr 26, 2023

Squash and Merge #950

a73d5c2

cuihtlauac mentioned this pull request Apr 27, 2023

Better differentiate between kinds of code samples #961

Open

Cuihtlauac ALVARADO and others added 19 commits May 19, 2023 14:24

Add exercises

74308d6

Apply suggestions from code review

2ae4c58

Grammar fixes Co-authored-by: Christine Rose <[email protected]>

Apply suggestions from code review

3a78203

Co-authored-by: Miod Vallat <[email protected]>

Some fixes

c62a6a2

Update text after letting it rest for a while

6054320

Add feedback from @gpetiot

baed030

More feedback from @gpetiot

28bac91

Add feedback from @xvw

dc571d3

Apply suggestions from @christinerose

e9afbff

Co-authored-by: Christine Rose <[email protected]>

Update ds_05_seq.md

eb9ba22

Minor edits

0025c88

Delete accidentaly imported files

fd49da0

Add realworldocaml ref

76f23e2

Fix Exit exception text

80c8538

Add Fun.protect text

6299385

Fix sample syntax

8b5525a

Fix references text

4574f58

Include more feedback

7e8bf10

More feedback

d880767

cuihtlauac pushed a commit that referenced this pull request May 19, 2023

Squash and merge PR #950 (Improve Error Handling Documentation) doc-e…

caff977

…rror at 4bd8925

cuihtlauac force-pushed the doc-error branch from 8a6db55 to d880767 Compare May 20, 2023 04:48

sabine pushed a commit that referenced this pull request May 22, 2023

Squash and merge PR #950 (Improve Error Handling Documentation) doc-e…

9b3e9b7

…rror at 4bd8925

sabine pushed a commit that referenced this pull request May 23, 2023

Squash and merge PR #950 (Improve Error Handling Documentation) doc-e…

08aabe2

…rror at 4bd8925

sabine reviewed Jun 5, 2023

View reviewed changes

data/tutorials/lg_08_error_handling.md Outdated Show resolved Hide resolved

tmattio added the new-doc Track creation of new content for the OCaml Documentation label Jun 6, 2023

sabine pushed a commit that referenced this pull request Jun 7, 2023

Squash and merge PR #950 (Improve Error Handling Documentation) doc-e…

4165897

…rror at 4bd8925

Update data/tutorials/lg_08_error_handling.md

c6adbf8

sabine merged commit 5d3f3ab into main Jun 7, 2023

sabine deleted the doc-error branch June 7, 2023 08:43

tmattio linked an issue Jul 19, 2023 that may be closed by this pull request

Error Handling #1412

Closed

	parts of an application and can't be isolated in dedicated module. In contrast
	parts of an application and can't be isolated in a dedicated module. In contrast

	to several other main stream languages, OCaml provides several mechanisms to
	to several other mainstream languages, OCaml provides several mechanisms to

	handled exceptional circumstances, all with good runtime performances and code
	handle exceptional circumstances, all with good runtime performance and code

	partice. Later, it always require some thinking, which is good since proper
	practice. Later, it always requires some thinking, which is good since proper

	than the others, and is should be matter of adequacy to the context rather some
	than the others, and is should be matter of adequacy to the context rather than

	And you will get a stack trace. Alternatively, you can call, from within the program,
	This will produce a stack trace. Alternatively, you can call, from within the program,

	concern](https://en.wikipedia.org/wiki/Cross-cutting_concern), it touches all
	concern](https://en.wikipedia.org/wiki/Cross-cutting_concern); it touches all

	partice. Later, it always require some thinking, which is good since proper
	pratice. Later, it always require some thinking, which is good since proper

	management of errors shouldn't ever be overlooked. No error handling is better
	error management shouldn't ever be overlooked. No error handling is better

	than the others, and is should be matter of adequacy to the context rather some
	than the others, and it should be matter of adequacy to the context rather some

	# let rec loop x = x :: loop x
	# let rec loop x = x :: loop x;;

Improve Error Handling Documentation #950

Improve Error Handling Documentation #950

Uh oh!

Conversation

cuihtlauac commented Feb 23, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christinerose left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cuihtlauac commented Mar 2, 2023

Uh oh!

Uh oh!

Uh oh!

rikusilvola Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rikusilvola commented Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cuihtlauac commented Mar 2, 2023

Uh oh!

christinerose left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

cuihtlauac commented Feb 23, 2023 •

edited

Loading

rikusilvola Mar 2, 2023 •

edited

Loading

rikusilvola commented Mar 2, 2023 •

edited

Loading

Tchou commented Apr 26, 2023 •

edited

Loading