Learning OCaml has been quite a harsh journey for myself, especially as someone who didn’t know anything (and still doesn’t know much) about type systems and the whole theory behind programming languages. (Functional languages, it seems, use a lot of very advanced concepts and it can be quite hard to understand OCaml code without understanding the theory behind it.)

But I digress, I wanted to write this note to “past me” (and anyone like that guy). It’s a note about what you should do to get past the OCaml bump. There’s two things: getting used to read types, and understanding how to parse compiler errors.

For the first one, a breakthrough in how effective I am at reading OCaml code came when I understood the importance of types. I’m used to just reading code and understanding it through variable names and comments and general organization. But OCaml code is much more like reading math papers I find, and you often have to go much slower, and you have to read the types of everything to understand what some code does. I find that it often feels like reverse engineering. Once you accept that you can’t really understand OCaml code without looking at type signatures, then everything will start falling into place.

For the second one, the OCaml compiler has horrendous errors it turns out (which I presume is the major reason why people give up on OCaml). Getting an OCaml error can sometimes really feel like a death sentence. But surprisingly, following some unwritten heuristics can most often fix it. For example, when you see a long-ass error, it is often due to two types not matching. In these kind of situations, just read the end of the error to see what are the types that are not matching, and if that’s not enough information then work you way up like you’re reading an inverted stack trace. Another example is that long errors might actually be several errors concatenated together (which isn’t really clear due to formatting). Copy/pasting errors in a file and adding line breaks manually often helps.

I’m not going to write up exactly how to figure out how each errors should be managed. Instead, I’m hopping that core contributors to OCaml will soon seriously consider improving the errors. In the mean time though, the best way to get out of an error is to ask on on discord, or on stackoverflow, how to parse the kind of errors you’re getting. And sometimes, it’ll lead you to read about advanced features of the language (like polymorphic recursion).