ocaml

OCaml Development

Core Philosophy

1. Interface-First Design: Design the .mli file first. A clean interface matters more than clever implementation.
2. Modularity: Build small, focused modules that do one thing well. Compose them for larger systems.
3. Simplicity (KISS): Prioritize clarity over conciseness. Avoid obscure constructs.
4. Explicitness: Make control flow and error handling explicit. Avoid exceptions for recoverable errors.
5. NEVER use Obj.magic: It breaks type safety. There is always a better solution.

Build System and Tooling

• Build: Use dune exclusively
• Formatting: Run dune fmt before committing (uses ocamlformat)
• Common Libraries:
  • Concurrency: eio
  • Structured output: fmt
  • Logging: logs
  • CLI parsing: cmdliner
  • JSON: jsont
  • HTTP: cohttp-eio

Module Interface Design

Documentation Pattern

Write ocamldoc in the voice of a POSIX manual page. Full sentences, no extraneous detail, no colons or em dashes joining clauses, and nothing about the implementation. Load the doc-style skill before writing or changing any comment. It is the full standard and this section is only its summary.

Every .mli file starts with a synopsis, then a blank line, then the description.

(** User accounts and profiles.

    Users are workspace members. A user is identified by an {!type:id} that is
    stable for the lifetime of the account. *)

Function Documentation

Open with the function applied to its arguments, followed by is:

val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)

val find : id -> t -> user option
(** [find id t] is the user of [t] with identifier [id], or [None] if [t] has
    no such user. *)

Reserve an active verb for functions that exist for their effect:

val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)

For types, describe what the values represent, never their representation: