The OCaml.org team has yet another draft tutorial. This time, the title is: “Mutability, Loops, and Imperative Programming”. We want your feedback on it:
One of my favorite parts about OCaml as a language is how easy it is to describe more “advanced” features from first principles. In this case, refs are essentially just a record with a single mutable field + some custom operators (i.e. !, :=). The tutorial does touch on this with the “References Are Single Field Records” section, but I honestly think the first part about refs should be removed in favor of this one.
I would get rid of the external ref = ... part by changing the REPL line to be #show_type instead of #show. The C FFI part of the tutorial is linked, but even this isn’t super useful because %makemutable isn’t a C function but a lambda one.
The “Byte Sequences” section doesn’t really mention much of a distinction between string and bytes, which might not be intuitive to beginners.
The rest of the article I generally agree with (particularly the recommendations), but I do wonder if the get_char function is too complicated for someone unfamiliar with Unix programming. I’ll defer to others on that question, though.
I suggest to not show the current %makemutable implementation of ref. You can, however, show how it could be implemented using the record syntax (and which happens to be as fast as %makemutable), along deref and assign:
let create v = { contents = v };;
Regarding Bytes, there is one critical point that is missing, in my opinion. Such arrays are much more compact (by a factor 8) than char array, and thus should always be used, unless one is stuck with array polymorphism.
The example of get_char, especially its first implementation, is a bit too ugly for a tutorial.
Regarding control flow, it should start by saying that let in is a sequence point for mutable effects. One should not need to read until the very end of the tutorial to discover the issue with side effects in arguments. Also, the sequence should be explained as just being syntactic sugar for let () = ... in rather than a primitive construction of the language.
The char_cos example should not redefine the value of pi, which is especially ironic since, later in the anti-patterns, it is written “do not shadow existing definitions, give a descriptive name”.
The following sentence is awful: “It is possible to use an imperative programming style without losing the benefits of type and memory safety.” The reader is left under the wrong impression that using an imperative OCaml programming would cause type and memory unsafety. More generally, the whole paragraph “functional by default” is really patronizing.
makemutable will not be shown. As suggested by @zbaylin and @K_N, we’re now using #show_type in the PR. Sorry, I’ve not yet updated the page in staging.
I’ll add your create function; excellent suggestion, thanks.
BTW, do you share @zbaylin opinion on merging “References” and “References Are Single Field Records” into a single section after “Mutable Record Fields”?
Good point; I’ll add that, too.
I agree it is not very nice, especially the first one. Ideally, I’d prefer not to define anything and use something available in the examples later. Not sure how to improve that.
let in to put things in sequence: agreed
Bring side effects in arguments: Where would you prefer to see this?
; as syntactic sugar: It’s not the same as ( + ) or ( |> ). Isn’t it going to be confusing?
If the suggestion is to start by explaining the possibility of having mutable fields inside records, and only then present references as some sugar over single-field ones, then I agree.
In the very first tutorial, since it already has sections about “functions with side effects” and “local definitions”. I don’t see any reason to delay this piece of information till the end of the seventh tutorial.
I don’t understand. Why would it confuse users to be told that a;b is just sugar for let () = a in b?
