4 ms·

My biggest frustration with the Ocaml is with third-party libraries documentation. The majority of the docs are just function signatures without explanation, le

My biggest frustration with the Ocaml is with third-party libraries documentation. The majority of the docs are just function signatures without explanation, let alone usage examples. The language however is quite nice and the stdlib is fairly complete. Edit: Another problem I see is the (over?) reliance on PPX preprocessors. It does make a lot of tasks simpler, but it is too much magic for me personally.

rbjorklin 6y ago
I wholeheartedly agree with everything you said! What’s making the PPX situation even worse is that they seem to break with every new release of the compiler.
- kdkeyser 6y ago
  I second this. I dislike the liberal usage of metaprogramming, especially in the context of a code base that you have to work on with multiple people. It adds another layer of concepts/complexity/magic that everyone in the team has to learn. With PPX, the barrier to use metaprogramming has become lower (especially compared to camlp4), resulting in most modern Ocaml codebases depending on it. But the ergonomics of the end-to-end software delivery have not really followed: the fact that PPX's break between compiler versions means that in practice, a compiler upgrade becomes a very costly thing to do. It is difficult to make the case for this in an industrial setting, where languages with almost religious backwards compatibility are common (Java, C++, even Go). For Ocaml, it is especially sad, because the core language is already quite powerful and expressive, lowering the need for metaprogramming (imo). For scenarios where code generation is needed, I prefer a separate code generation step, which produces explicit "standard" code (e.g. like protoc)
aldanor 6y ago
It's funny that I could say the opposite about Rust if you asked what I enjoy most about the ecosystem - many third party libraries have outstanding documentation. Wonder why is that - in the end, it's just some folks like you and me spending their free time writing those. Why is it different for different languages then, is it the tooling like rustdoc and docs.rs or just the standards set by the community? Not sure.
- nestorD 6y ago
  I can't speak for others but for me it is the tooling. Knowing that I can get great online doc with a single command is a very good motivation to start writing said documentation.
- Legogris 6y ago
  I've not been deeply involved in either so take my hunch for what it is: OCaml is an academic language like Haskell. Academics tend to neglect documentation in general, be it because what they're working on is mostly self-serving, lack of time/enthusiasm or a tinge of elitism on that "this should be obvious and if not just read the code". Rust adherents seem to really want to take over the world and they realize that great documentation is an enabler for that. Also the standard libraries and compiler set a pretty strong precedent.
  - yawaramin 6y ago
    Disagree, somewhat. You should check out the OCaml manual: https://ocaml.org/releases/4.11/htmlman/ https://ocaml.org/releases/4.11/htmlman/ It is a complete and up-to-date manual of the entire OCaml distribution, including executables, language, runtime, and standard library. It's rare to find modern industry-driven languages with this level of coherent documentation. But regarding third-party library documentation, that is indeed spotty. Some people publish it, some don't. I have to reluctantly conclude it's due to a lack of tooling which automates the tedious processes.
- gameswithgo 6y ago
  Some of it is probably accident of history. Some of it can be driven by external factors: javascript was the only choice for an important domain for a long time. Some if it I think is due to attractive syntax, or tooling. Python for example, horrible runtime performance, but people were drawn to it for probably syntax and tooling reasons. Comparing Rust and OCaml: The OCaml syntax is a bit odd. I was quite taken by F#, which is a very similar language to OCaml, but with some of the cumbersome syntax removed. F# seemed quite nice, looking at OCaml it just felt horrible and I didn't want to deal with it. In practice I know it would be fine, just like you get used to Lisp and it's parens, but there is a real psychology there that turns people away. OCaml has good runtime performance, but its not the kind of language that will draw in C/C++ programmers or work for domains where you need C or C++ currently. Lack of multi-core is a huge turn off for a lot of people. This is the era where multi-core is our only path to more performance! Rust syntax is a little more familiar to people, the runtime performance is top notch, very good at leveraging more cores, and maybe most importantly the community has made a concerted effort to make the language as approachable as possible. With good/friendly documentation and community. Easy install process, decent editor support, etc. Go ask a question about "Which way is faster" in a C# forum, you get a lecture about how you shouldn't worry about that. On a Rust forum you get an deep dive into performance concerns and language design. This seems to have drawn in people from communities you wouldn't expect. A low level, complicated language that Ruby and Javascript developers are drawn to? An interesting result!

rbjorklin 6y ago

I wholeheartedly agree with everything you said! What’s making the PPX situation even worse is that they seem to break with every new release of the compiler.

kdkeyser 6y ago
I second this. I dislike the liberal usage of metaprogramming, especially in the context of a code base that you have to work on with multiple people. It adds another layer of concepts/complexity/magic that everyone in the team has to learn. With PPX, the barrier to use metaprogramming has become lower (especially compared to camlp4), resulting in most modern Ocaml codebases depending on it. But the ergonomics of the end-to-end software delivery have not really followed: the fact that PPX's break between compiler versions means that in practice, a compiler upgrade becomes a very costly thing to do. It is difficult to make the case for this in an industrial setting, where languages with almost religious backwards compatibility are common (Java, C++, even Go). For Ocaml, it is especially sad, because the core language is already quite powerful and expressive, lowering the need for metaprogramming (imo). For scenarios where code generation is needed, I prefer a separate code generation step, which produces explicit "standard" code (e.g. like protoc)

aldanor 6y ago

It's funny that I could say the opposite about Rust if you asked what I enjoy most about the ecosystem - many third party libraries have outstanding documentation. Wonder why is that - in the end, it's just some folks like you and me spending their free time writing those. Why is it different for different languages then, is it the tooling like rustdoc and docs.rs or just the standards set by the community? Not sure.

nestorD 6y ago
I can't speak for others but for me it is the tooling. Knowing that I can get great online doc with a single command is a very good motivation to start writing said documentation.
Legogris 6y ago
I've not been deeply involved in either so take my hunch for what it is: OCaml is an academic language like Haskell. Academics tend to neglect documentation in general, be it because what they're working on is mostly self-serving, lack of time/enthusiasm or a tinge of elitism on that "this should be obvious and if not just read the code". Rust adherents seem to really want to take over the world and they realize that great documentation is an enabler for that. Also the standard libraries and compiler set a pretty strong precedent.
- yawaramin 6y ago
  Disagree, somewhat. You should check out the OCaml manual: https://ocaml.org/releases/4.11/htmlman/ https://ocaml.org/releases/4.11/htmlman/ It is a complete and up-to-date manual of the entire OCaml distribution, including executables, language, runtime, and standard library. It's rare to find modern industry-driven languages with this level of coherent documentation. But regarding third-party library documentation, that is indeed spotty. Some people publish it, some don't. I have to reluctantly conclude it's due to a lack of tooling which automates the tedious processes.
gameswithgo 6y ago
Some of it is probably accident of history. Some of it can be driven by external factors: javascript was the only choice for an important domain for a long time. Some if it I think is due to attractive syntax, or tooling. Python for example, horrible runtime performance, but people were drawn to it for probably syntax and tooling reasons. Comparing Rust and OCaml: The OCaml syntax is a bit odd. I was quite taken by F#, which is a very similar language to OCaml, but with some of the cumbersome syntax removed. F# seemed quite nice, looking at OCaml it just felt horrible and I didn't want to deal with it. In practice I know it would be fine, just like you get used to Lisp and it's parens, but there is a real psychology there that turns people away. OCaml has good runtime performance, but its not the kind of language that will draw in C/C++ programmers or work for domains where you need C or C++ currently. Lack of multi-core is a huge turn off for a lot of people. This is the era where multi-core is our only path to more performance! Rust syntax is a little more familiar to people, the runtime performance is top notch, very good at leveraging more cores, and maybe most importantly the community has made a concerted effort to make the language as approachable as possible. With good/friendly documentation and community. Easy install process, decent editor support, etc. Go ask a question about "Which way is faster" in a C# forum, you get a lecture about how you shouldn't worry about that. On a Rust forum you get an deep dive into performance concerns and language design. This seems to have drawn in people from communities you wouldn't expect. A low level, complicated language that Ruby and Javascript developers are drawn to? An interesting result!