I had wondered:
Is it “poor taste” to include type information in function definitions?
It seems like very nice documentation, but then again, maybe it is nicer rely on the inferencing engine to reduce the amount of code?
In theory you write short, easy to understand functions; in practice it isn’t always this simple though.
People kindly replied:
When you can avoid it, it is better to NOT include type information. Using a tool like “ocamldoc” will render the function and its inferred types in a real documentation format (e.g. HTML).
There are cases where you need to include type information, but they are corner cases.
Interface files (.mli) are usually the main place for documentation. Within the .ml files, you can explain your algorithms but it’s usually just plain comments, not so much type annotations.
As to the matter of “taste”, note that this practice is not idiomatic in Ocaml, in contrast to Haskell where it seems current. I’m not sure if that’s your case, but people coming to Ocaml from Haskell may at first tend to exaggerate on this aspect…