"OCaml -- first impressions"

Learning
1

In the spirit of honest and slightly frustrating reality checks, there is an interest blog post by Anders Hovmöller, OCaml — first impressions. I’ll quote the “list of reactions” below for easier commenting:

  1. Calling their REPL “toplevel” is a bit confusing

  2. The REPL needs some serious work: no multiline editing, I can’t move the cursor with arrow keys, no history

  3. The talk of “two standard libraries” (Core vs Batteries) makes me uneasy

  4. It seems the community hasn’t settled on a standard build system

  5. Books and documentation gives examples of misleading code (due to inconsistent indent) because the compiler doesn’t give you warnings or errors. It seems to me like an unnecessary usability flaw.

  6. No iPhone app. This would be nice to play around on the train to/from work. I am a big fan of Pythonista so I miss this.

  7. Having to run “opam init” is weird. No other package manager I know of requires something like that. It tried to ask me to update my fish config but for some reason it seemed to have answered “no” by default and continued.

  8. opam output while running is quite pretty

  9. When reading examples it looks a little bit like OCaml has significant whitespace but only in a few very rare cases. Reading more it looks like not. I think it would be better if the language was consistent and easy to understand. I prefer significant white space, coming from Python, but the automatic insertion of “;;” in some seemingly (to newbies) random places in the grammar looks quite icky to me. It’s especially icky because it doesn’t even require newlines, so “let foo = 1 let bar = 2;;” is valid even though there’s no newline before the second let.

  10. The manual is super ugly :stuck_out_tongue:

  11. The manual has weird choices like starting a section with the full BNF grammar. If the manual is for compiler writers, then it shouldn’t be called “the manual”! If it’s not for compiler writers, the BNF grammar should be in a reference section, not the first thing you have to scroll past.

  12. Feedback in the REPL needs work (notice that it says “the highlighted” but nothing is in fact highlighted):

     # let foo = (1;;

    Syntax error: ‘)’ expected, the highlighted ‘(’ might be unmatched

  13. In general a lot of syntactical errors just ends up with the error “Syntax error” without any more information, at least in the REPL.

  14. Copy pasting the first example on the “learn” section on the homepage to a file and running it produces the error reproduced below. The problem is that while it’s formatted as one piece of code, it’s actually a bunch of snippets that have to be separated by “;;”, and even then it’s not runnable because it requires the definition of the variable “l”. Even worse, these examples are pretty terrible in trying to show the feel of a language to a beginner. Compare with the homepages of Python or Ruby.

  15. See:
    ➜ ~ ocaml foo.ml
    File “./foo.ml”, line 3, characters 15-21:
    Error: This expression has type float → float → float
    but an expression was expected of type
    ('a →
    'b →
    'c → 'd → 'e → 'f → 'g → 'h → 'i → 'j → 'k → 'l - > 'm) →
    'n →
    'a →
    'b → 'c → 'd → 'e → 'f → 'g → 'h → 'i → 'j → 'k → 'l → 'm
    Type float is not compatible with type
    'a →
    'b → 'c → 'd → 'e → 'f → 'g → 'h → 'i → 'j → 'k → 'l → 'm

  16. Strings are 8-bit only. No Unicode in the standard library. This is really quite unforgivable in 2017

8 Likes
2

I hope to get the “Syntax error” problem fixed as a medium-term consequence of using a menhir-generated parser, but there is still quite a bit of work to be done in this direction.

4 Likes
3

Some of the points are just “OCaml isn’t python”.

13 Likes
4

Well I think we can’t expect a first-week user to only make accurate points. But I think the list is still useful in both the parts that are correct and the parts that are incorrect, to give us a sense of what people notice first, what confusions arise, and maybe help pick low-hanging fruit for experience improvements. And there are also things that are just meh, feel free to ignore them!

(For example, I hadn’t thought about the style of the manual in a while, and I still don’t know whether that is really important, but we could probably decide to change the CSS to look more like readthedocs if we wanted to, and it may not even be that much work. Do we want to?)

18 Likes
5

Cleaning up the aesthetics of the manual seems like a great idea. It seems like an easy way to improve the appearance of the language for newcomers, and well worth the effort.

y

17 Likes
6

I agree that updating the manual css to better fit current web design trend would send a positive signal in term of vitality of the OCaml ecosystem. Moreover, it should not be that hard — i.e. I am adding this to my 4.06 todo list if no interested web designer manifests himself.

6 Likes
7

Ad 9. Do most people even use ;; except in the REPL? Maybe the manual could omit to mention ;; in the introductory parts, and use let () = ... for module-level code? There are only a few other cases where ;; is needed IIRC, and I doubt it will be an issue for beginners.

Ad 2. Maybe suggest utop instead? In addition to command-line editing, the completions should be extra useful for beginners.

The REPL could also have an option to commit on ENTER or SHIFT-ENTER instead of requiring ;; terminators.

4 Likes
8

Re: point 10. I almost went there last year when I added the ocaml-manual packages.

I think it would be nice if any change in the look could be made as to blend well with odig/odoc default stylesheet so that people who opam install odig opam-manual get somehow a consistent view when they click on the manual link.

Depending on the exact time frame for 4.06 I could try to provide something.

2 Likes
9

Concerning other points,

This begs the question of why the original author did not find utop. Maybe, we should take drastic measure and add a link to utop in the basic ocaml repl?

Here the linked ocaml.org article is downright confusing: it starts with the idea that the use of ;; is hard to grasp and full of exceptions and make sure to realize this prophecy.

I don’t agree with this point, this part of the manual is explicitly self-described as a technical part of the manual, and I consider the BNF description to be at least as readable as the in-prose description of the grammar that follows. Moreover, ideally, all concepts described in this language reference part should have been covered somewhere in the tutorial part of the manual (there are few gaps currently), and this part of the manual (language extensions excepted) should be only a technical complement to the first part.

1 Like
10

I’m always surprised by the fact that people always mention that for OCaml but never do for go which has exactly the same representation for strings.

Maybe we should simply add in the String module that if strings are to be interpreted as text they should be interpreted as an UTF-8 byte sequence, people would then naturally think that OCaml has unicode support in the standard library — which fundamentally it has.

5 Likes
11

That sounds like a nice idea, would you care for a pull request? Insertion in relevant places of the manual could also help, maybe.

12

Another probable source of confusion is the toplevel itself which escapes non-ascii characters:

"한글";;
- : string = "\237\149\156\234\184\128"

I could totally see someone learning the language by playing with the toplel concludes from the above snippet that OCaml has no unicode support.

6 Likes
13

That sounds like a nice idea, would you care for a pull request?

Maybe. But not immediately. When is 4.06 freeze ?

14

mid-September, I think. But I like 4.07 as well :slight_smile:

@octachron thanks for your many relevant comment in the thread. I trust to do turn some of them into actions!

1 Like
15

For people interested with the toplevel string escaping problem, here is a live PR on the subject https://github.com/ocaml/ocaml/pull/1231 .

3 Likes
16

Somehow I started this documentation PR but then I got distracted, see https://github.com/ocaml/ocaml/pull/1232

1 Like
17

Yeah, I’m looking forward for UTF-8 byte sequence support!

utop # "私は瀧です";;
- : string = "\231\167\129\227\129\175\231\128\167\227\129\167\227\129\153"
18

@taki If you are too annoyed, you can do meanwhile:

opam install uuseg
# #require "uuseg.string";;
# #install_printer Uuseg_string.pp_utf_8;;
# "私は瀧です";;
- : string = 私は瀧です

(which in general will do a slightly better job than PR1231)

6 Likes
19

These remarks are somewhat linked to those in here.

I also want to emphasize how accurate and important these remarks are. The language has its quirks and weirdnesses, but all languages do and I’m okay with that. The thing that really needs improving if we’re to attract new users is exactly the title of the topic: first impressions.

When you have a heavy imperative-programming background such as lots of people have (me included), getting a grip on functional programming is hard enough; you don’t want to have to put up with petty problems due to inconsistent resources/behaviors such as the ones described by Anders. Let me give some examples:

  • Questions I think are important when you’re a beginner
    • WTF, I can’t mutate?! How can I do anything without mutating? :scream:
    • Where are my for loops? :sob:
    • Pattern-matching, you say? :face_with_raised_eyebrow:
    • I got a type error, why is that? :anguished:
    • And so on…
  • Questions a beginner shouldn’t bother with
    • The REPL sucks, is there a way to get anything done with it? :angry:
    • When am I supposed to use ;;? What does it even mean? :thinking:
    • Ok, I installed OCaml. Now where’s a good tutorial?
    • And so on…

Same applies to OPAM. As discussed here, OPAM is giving new users a hard time and this is penalizing OCaml as a whole when it comes to attracting new users.

With all of that combined, you lose interest in learning. As a proof, the article @gasche cites is entitled “First impressions” and it doesn’t mention OCaml’s features at all.

7 Likes
20

Why do you think that this points are meaningful to attract new users?
It’s more likely that newbie will be turned off by the lack of multithreading or ad-hoc overloading (especially for numeric types) than by missing iPhone app (lol) or old-school CSS in the manual.