code-style

OCaml Code Style

Core Philosophy

1. Interface-First: Design .mli first. Clean interface > clever implementation.
2. Modularity: Small, focused modules. Compose for larger systems.
3. Simplicity (KISS): Clarity over conciseness. Avoid obscure constructs.
4. Explicitness: Explicit control flow and error handling. No exceptions for recoverable errors.
5. Purity: Prefer pure functions. Isolate side-effects at edges.
6. NEVER use Obj.magic: Breaks type safety. Always a better solution.

Naming Conventions

Element	Convention	Example
Files	lowercase_underscores	user_profile.ml
Modules	Snake_case	User_profile
Types	snake_case, primary type is t	type user_profile, type t
Values	snake_case	find_user, create_channel
Variants	Snake_case	Waiting_for_input, Processing_data

Function naming:

• find_* returns option (may not exist)
• get_* returns value directly (must exist)

Avoid: Long names with many underscores (get_user_profile_data_from_database_by_id).

Refactoring Patterns

Option/Result Combinators

(* Before *)
match get_value () with Some x -> Some (x + 1) | None -> None

(* After *)
Option.map (fun x -> x + 1) (get_value ())

Prefer: Option.map, Option.bind, Option.value, Result.map, Result.bind

Monadic Syntax (let*/let+)

(* Before - nested matches *)
match fetch_user id with
| Ok user -> (match fetch_perms user with Ok p -> Ok (user, p) | Error e -> Error e)
| Error e -> Error e

(* After *)
let open Result.Syntax in
let* user = fetch_user id in
let+ perms = fetch_perms user in
(user, perms)

Pattern Matching Over Conditionals

(* Before *)
if x > 0 then if x < 10 then "small" else "large" else "negative"

(* After *)
match x with
| x when x < 0 -> "negative"
| x when x < 10 -> "small"
| _ -> "large"

Function Design

Keep functions small: Under 50 lines. One purpose per function.