OOCCaammll:: FFiirrsstt DDaattee

Published February 21, 2022

Last month I _s_w_i_p_e_d _r_i_g_h_t _o_n _O_C_a_m_l[1]. How did the first date go? We get
along well, and this could be the start of a mutually enjoyable
relationship.

TTuurrnn--oonnss

_S_y_n_t_a_x

First impressions are superficial and good looks donʼt create a
relationship, but since youʼll be staring at one another for hours on end,
there should be some physical attraction.

In that regard, OCaml makes a favorable impression. I find the syntax
pleasant to look at and converse with. Thereʼs a nice balance between
succinct and verbose. OCaml is mostly just space-separated words: no parens
for function calls, no curly braces. But sheʼs not afraid to be explicit
with punctuation when needed.

I do miss having a clean marker to close blocks. OCaml has bbeeggiinn and eenndd
keywords for this (aliases for parentheses). Unfortunately, _o_c_a_m_l_f_o_r_m_a_t[2]
replaces them with literal parens. Standardized formatting is important, so
Iʼve let that go. Incidentally, ooccaammllffoorrmmaatt is fast and relatively
consistent.

I like having nested comments again (I miss them in Go). I also like that
OCaml lacks import statements. Instead, it uses module prefixes (like
SSyyss..ggeettccwwdd) which automatically load the relevant module. Module prefixes
also make it clear which function Iʼm calling. If they get too verbose,
lleett ooppeenn SSyyss factors them out during a small scope.

Ocamlʼs lightweight syntax for modules is handy for minting local
namespaces. It helps me avoid stuttering function names (ffoooo__aa, ffoooo__bb,
ffoooo__cc, …).

_S_e_m_a_n_t_i_c_s

I had forgotten how much I enjoy algebraic data types, generics, partial
function application, pattern matching, type inference, and exhaustive
pattern matching. Iʼm really glad to have them available again.

Iʼve been pleased with OCamlʼs type checking on pprriinnttff and the way that
__PP__rr__ii__nn__tt__ff__..__kk__ss__pp__rr__ii__nn__tt__ff[[11]]

11:: hhttttppss::////ooccaammll..oorrgg//aappii//PPrriinnttff..hhttmmll##VVAALLkksspprriinnttff
lets me reuse formats in my own functions.

OCaml strikes a nice balance between functional, impertative, and
object-oriented paradigms. Deep inside the machine, itʼs all just pointers
and mutable memory. Sometimes I want to cut through all the abstractions
and just mutate an array. Other times I like pretending that I live in a
magical world of composable functions and immutable data. I typically favor
opinionated languages, but this is one area where Iʼm glad to have choices.

Iʼm puzzled that the OCaml community doesnʼt use objects (the O in OCaml)
more frequently. So far, OCaml has the best object system Iʼve encountered.
I may write a separate article about it, but it really is great.

Logic programming is the only paradigm I miss in OCaml. Surprisingly often,
I wish I could define a function as a succinct Prolog predicate. Maybe
Iʼll write a library for it someday.

Anyway, all of this makes OCaml great for refactoring. When I change a
design, the type checker quickly identifies everything I need to review (tools
like _m_e_r_l_i_n[3] make it even easier). If thereʼs redundancy, I can factor
out a local function. If thatʼs useful, I can make it a global function.
Then I can move global functions into a file-local module. Then I can move
those modules into separate packages to share with other projects. If
modules donʼt feel right, I can bundle functions into records or objects.
Or maybe all I need is a higher-order function.

That may sound complex, but all modern languages have these abilities.
Itʼs just that OCaml somehow makes them feel comfortable and integrated. I
canʼt put my finger on the exact cause, but refactoring OCaml has been a
pleasure.

_T_o_o_l_s

OCaml tooling leaves a good impression. _o_p_a_m[4] builds everything from
source, so if ooppaamm iinnssttaallll works, Iʼm confident that Iʼll be able to hack
on the libraryʼs source code later when I need to fix bugs. Binary package
managers are faster, but donʼt offer this assurance. I think this is the
right trade off for a programming language package manager.

__dd__uu__nn__ee[[11]]

11:: hhttttppss::////dduunnee..bbuuiilldd
is fast and reliable. It scatters config files all over, but that buys you
the ability to put code anywhere in your repository and have it build on
the first try. (Iʼve toyed with this as the basis for a very simple ooppaamm
replacement).

I was skeptical of mmeerrlliinn since I usually find IDE features more
distracting than helpful. To my surprise, merlinʼs type hints and error
messages (in emacs at least) never intrude on my flow. They only appear
when requested. For example, CC--cc CC--tt shows the inferred type at the cursor,
or CC--cc CC--xx shows errors without the cost of doing a full build. iimmeennuu even
shows inferred types for function definitions. mmeerrlliinn is a helpful
companion.

_C_o_m_p_i_l_e_r

OCamlʼs native code compiler is fast enough that I use it almost
exclusively. It also produces fast code. If Iʼm iterating quickly, I
sometimes use the interpreter or toplevel.

I enjoy ##!!//uussrr//bbiinn//eennvv ooccaammll for small scripts. Itʼs great to have the
compiler catch my silly scripting mistakes early. It took me a while to
discover this, but you can load modules in an OCaml shell script with
##uussee ""ttooppffiinndd"" followed by ##rreeqquuiirree ""FFoooo"" (but merlin
_d_o_e_s_nʼ_t _p_a_r_s_e _t_h_o_s_e _d_i_r_e_c_t_i_v_e_s[5] yet).

OCaml compiler errors are clear and informative. Read them from the bottom
upwards. The bottom has precise information, above is the context. Since
terminals scroll off the top, this makes a certain kind of sense, but itʼs
different than reading English from top to bottom. In the end the direction
doesnʼt seem to matter much.

OCamlʼs backtraces might be the best Iʼve seen. I wish they were on by
default, but you can enable them by compiling with ooccaammlloopptt --gg then adding
bb to the OOCCAAMMLLRRUUNNPPAARRAAMM environment variable. If you set OOCCAAMMLLRRUUNNPPAARRAAMM at
all, whether bb or otherwise, be sure to clear it before running opam. Iʼve
had several ooppaamm iinnssttaallll or ooppaamm uuppddaattee fail because it was set.

Anyway, OCamlʼs backtraces are informative without being cluttered. They
clearly indicate where an exception originated and where it was re-raised.

_E_r_r_o_r _h_a_n_d_l_i_n_g

Iʼm still exploring error handling to find an idiom with tradeoffs that I
like. I may write up a detailed article once I settle on something.

Until then, OCaml is a good reminder of how clean and composable code can
be when using exceptions for error handling. C and Go treat errors as plain
values, so your happy path gets cluttered with boilerplate. Haskell uses
error monads, so everyone has to agree on one monad. Exceptions avoid those
two problems (while introducing others). There are tons of trade offs in
this space, otherwise, all languages would have settled on the same idiom
for handling errors.

OCaml can do errors as values, or errors in monads, or errors via
exceptions. It can also signal errors with polymorphic variants (feels like
lightweight, checked exceptions).

Ideally a clear error handling paradigm for OCaml would have emerged by now,
so we could have one idiom throughout the ecosystem. Since that hasnʼt
happened, itʼs nice to have choices so that developers can continue
exploring the territory.

_C_o_m_m_u_n_i_t_y

The community is surprisingly healthy, in the sociological sense. The
people are kind, my pull requests get meaningful feedback, discussions
cover technical merits without drama. I think that software communities are
healthier places than the headlines make them sound, but OCaml has done
really well in this area.

Part of the welcoming feel is that the core OCaml code base is easy to
navigate. Iʼve had no trouble poking around the standard library or the
runtime. The language specification is easy to read. The language grammar
is informative.

The community is also remarkably productive. As Iʼve followed commits and
pull requests, Iʼve been amazed at how much is getting done by so few
people. Thereʼs some amazing talent here. Iʼm sure that Iʼll learn a lot
just by watching them at work.

TTuurrnn--ooffffss

Relationships with software and with humans differ in at least one major
way: the former welcomes patches, the latter shuns them. If you donʼt
believe me, try suggesting that your partner get plastic surgery or start a
diet ;;--))

Yes, I realize that I can contribute to open source projects to fix
problems. I do contribute when cost-benefit balance tilts the right way.

_M_e_s_s_i_n_e_s_s

OCamlʼs ecosystem and culture give me a sense of messiness and disorder.
The issue trackers are littered with old, open issues or abandoned pull
requests. The standard library has an inconsistent feel. There are a dozen
new projects up in the air. Everywhere I look there are too many pieces
floating around, and theyʼre all tangled together. To be clear, this is
not the case with OCamlʼs core semantics which feel focused, orderly, and
orthogonal.

An example may prove useful. Reading OCaml documentation often goes like
this: I look up ffoooo xx yy whose documentation says that itʼs the same as
bbaarr 00 xx yy, whose documentation says that itʼs the same as bbaazz ((xx++yy)) 00.
After following this chain of pointers, I juggle those pieces in mind while
reading about bbaazz, then unwind my mental stack back to ffoooo, which I
actually care about.

I realize that, under the hood, code reuses code but that complexity
shouldnʼt shine through in APIs, documentation, or abstractions. When I
want to understand ffoooo, there are too many pieces in play. This isnʼt just
about documentation, the abstractions, opam dependencies, and APIs often
have this tangled feel. Dereferencing pointers _c_a_n be expensive for
machines, but it _i_s expensive for humans.

Another example: much of the OCaml ecosystem (like software generally) is
too configurable. For example, you can configure the OCaml compiler with at
least _1_1 _d_i_f_f_e_r_e_n_t _o_p_t_i_o_n_s[6]. Thatʼs not eleven total compilers, thatʼs
eleven combinatorial options resulting in 2048 possible compilers (are they
all viable?). Most opam packages have similarly configurable APIs making
them obese and unwieldy for the common case.

Let me back up. We come to relationships with subjective preferences. Those
preferences arenʼt right or wrong, they just are. My preference is for few
pieces, independence, and throwing things out. I donʼt have the mental
bandwidth to handle many pieces, dependencies, or nostalgia. These
preferences explain why my favorite software projects are OpenBSD and
_s_u_c_k_l_e_s_s[7]: they simplify brutally, DIY, and break compatibility if needed.

OCaml culture isnʼt objectively messy, it just feels messy to me. They
donʼt delete old functions from the standard library (most languages
donʼt), they still support antiquated releases, they use lots of large,
third-party libraries. Culturally they seem inclined to create a pointer to
somewhere else rather than inlining and optimizing (figuratively of course,
the compiler does inlining and optimization).

Iʼd like more _U_n_i_x _p_h_i_l_o_s_o_p_h_y[8] and less kitchen sink.

_D_o_c_u_m_e_n_t_a_t_i_o_n

Unlike the OCaml language spec, the module and function documentation in
OCamlʼs ecosystem is sparse at best. Its documentation typically describes
only a functionʼs purpose (the function name mostly did that already) and
exceptions that could arise. It almost never mentions edge cases, corner
cases, invariants, pre-conditions, post-conditions, computational
complexity, related functions, or best practices. Some opam authors do
better, but theyʼre outliers.

I donʼt necessarily want more words. I want more information.
Documentation is communication from a library author to her users. Reading
the source isnʼt enough. The source only describes how things are
currently implemented. It doesnʼt describe what is allowed to happen in
the future, or what constitutes a bug.

I have two theories about why OCamlʼs documentation is this way. My first
theory concerns types: languages with strong types lean too heavily on them
as documentation. Donʼt get me wrong, types are helpful for that purpose,
but theyʼre too much like source code: describing the implementation not
the interface.

My other theory concerns tools: OCaml documentation is mostly only viewable
in a web browser. Browsers are heavy, rarely available/decent on remote
servers, and compose poorly. Ocaml has nothing like mmaann, ppeerrllddoocc, ppyyddoocc, or
ggoo ddoocc for exploring and viewing documentation as text. The popular tools
are _o_d_i_g[9] (opens a browser tab), _o_c_p_-_b_r_o_w_s_e_r[10] (a curses tool), and
merlin (an editor tool, see mmeerrlliinn--ddooccuummeenntt in emacs).

If itʼs a pain to view documentation, nobody will do it; if nobodyʼs
viewing documentation, why write it?

My ideal for a documentation tool is one that displays, in a terminal,
• a list of installed libraries
• a list of modules within a library
• a summary of a single module
• a list of functions/types in a module
• modules/types/functions matching a keyword search
• functions matching a type signature
• a detailed description of a specific type/function

Wherever possible, results should be displayed one per line so that I can
use ssoorrtt((11)), ggrreepp((11)), aawwkk((11)), _e_t _a_l to script shortcuts and workflows.

CCoonncclluussiioonn

Thatʼs only two turn-offs and many turn-ons, so clearly my experience with
OCaml was positive.

Overall, I was surprised at how well OCaml did in choosing trade-offs and
focusing on what matters. I look forward to spending more time with her.

1: /ocaml-swipe-right/
2: https://github.com/ocaml-ppx/ocamlformat
3: https://github.com/ocaml/merlin/
4: https://opam.ocaml.org
5: https://github.com/ocaml/merlin/issues/1023
6: https://v3.ocaml.org/packages/search?q=ocaml-option
7: https://suckless.org
8: https://en.wikipedia.org/wiki/Unix_philosophy
9: https://erratique.ch/software/odig
10: https://v3.ocaml.org/p/ocp-browser/1.3.3