I didn’t find many resources for writing idiomatic readable ocaml code. The only one resource that I have found is : https://people.csail.mit.edu/dnj/teaching/6898/projects/vicente-wagner.pdf
But it talks about writing code using gof patterns. And it’s inclination is more towards object oriented style and uses classes more than functions, records and modules.
Any resources related to writing more readable, composable and less side effecty code.
There are some general guidelines here.
https://ocaml.org/docs/guidelines
More specific to your question:
https://ocaml.org/docs/guidelines#when-to-use-mutables
Our contribution guidelines for Dune contain a section on the kind of style that we encourage:
https://github.com/ocaml/dune/blob/main/doc/hacking.rst#general-guidelines
It’s obviously specific to the Dune code base so you will have to filter out ones that don’t make sense generally.
I’m reading the dune guidelines, and I think they’re too opinionated to be useful elsewhere.
My advice for readable code is the same as most other languages: use clear variable names. Use familiar patterns where possible (map, fold) rather than rolling your own functions. Separate out complex functionality into a function with a clear name. Write unit tests. Don’t be afraid to refactor to a more meaningful naming scheme. Try to go back and read your code and learn what works and what doesn’t for the reader. We are all readers of code more than writers – this is what’s important ultimately.
My advice specifically in OCaml is to avoid side effects as much as possible, and separate them out from pure code (as if you were writing haskell). This has very important effects (no pun intended) on your code. Pure code can only modify one or two things at a time, and that forces you to simplify your code – you have no other choice.
Not sure if this is what you seek or maybe you already know this but worth a mention for others that may find this topic.
While I’m very sinful in this regard, I strongly support OCaml beginners practice such discipline religiously for, say, three months.
It’s not about following it religiously. I think you get the most out of the language by following this advice in a general sense. The language is at its strongest when using functional paradigms. For performance-oriented reasons, these paradigms need to be broken sometimes. But every time you switch to mutation or other side effects, you’re trading code safety for performance or convenience. Monads are an option sometimes, but they come with their own costs.
A big program is just a collection of small functions.
Make each function do just one thing (but do it well).
Once you have a bunch of functions operating on the same thing, put them in a module.
Also, you will need some way to store your state in most programs. Since global state is generally frowned upon, that’s not a good option except for a few exceptions like debug state. OOP carries its state around inside the objects, with the massive downside that it’s very hard to know which functions modify or access which parts of an object’s state. In functional programming you will generally create a record that contains other records, each one to do with another part of your program state. It’s a good idea in general that each one of these record types should have its own module dealing with its needs and contents.