This style guide describes our code standards. It's a living document based on best practices we learn as we develop Onivim 2.
toStringfor a function that converts a type to a string.
Note: This goes against the OCaml convention of using a
t => string. The reason for this is that we've found the name
showto be ambiguous - for example, for
Window.show- what would the expected behavior be?
Window.toStringis much clearer.
optiontypes, use a variable name prefixed with
let maybeInt = Some(1)
Exceptions vs Result
In the OCaml standard library, there are often two 'versions' of a function - one that returns a result, and one that may throw an exception, ie:
Sys.getenv: t => string- may raise an exception if the environment variable 'var' is not present
Sys.getenv_opt: t => option(string)- returns an
However, for our code, we've flipped this - the 'default' version should be the one that returns an
option or a
result. The reason for this is that this documents the error in the type system - ensuring that the consumer handles it, and avoiding crashes!
Therefore, for function names, we'd recommend:
validate: string => result(t, string)
validateExn: string => t
Exn postfix shows that the function may throw an exception.
When not consuming a returned value, the type must be provided to prevent partial applications:
As an example, consider this block of code:
let _ = Event.subscribe(f, someEvent);
The problem here is that, if the signature of
Event.subscribe changes to add an extra parameter - the code here will still happily compile, but not do what we expect!
To prevent this from occurring, we required that the 'ignored' value must be described in one of the following ways:
let _: unit => unit = Event.subscribe(f, someEvent);
ignore(Event.subscribe(f, someEvent): unit => unit);