avsm/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: yojson
  • HTTP: cohttp-eio

Module Interface Design

Documentation Pattern

Every .mli file starts with a top-level doc comment:

(** User API

    This module provides types and functions for interacting with users. *)

Function Documentation

Use [function_name arg1 arg2] is ... pattern:

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

For values, describe what they represent:

type id = string
(** A user identifier. *)

Standard Interface for Data Types

For modules with a central type t, provide these functions where applicable:

| Function | Purpose | |----------|---------| | val v : ... -> t | Pure smart constructor (no I/O) | | val create : ... -> (t, Error.t) result | Constructor with side-effects | | val pp : t Fmt.t | Pretty-printer for logging/debugging | | val equal : t -> t -> bool | Structural equality | | val compare : t -> t -> int | Comparison for sorting | | val of_json : Yojson.Safe.t -> (t, string) result | Parse from JSON | | val to_json : t -> Yojson.Safe.t | Serialize to JSON | | val validate : t -> (t, string) result | Validate data integrity |

Abstract Types

Keep types abstract (type t) when possible. Expose smart constructors and accessors instead of record fields to maintain invariants.

Error Handling

Use result type for recoverable errors. Reserve exceptions for programming errors (e.g., Invalid_argument).

Central Error Type

Define a comprehensive error type in lib/error.ml:

(* In lib/error.mli *)
type t = [
  | `Api of string * Yojson.Safe.t
  | `Json_parse of string
  | `Network of string
  | `Msg of string
]

val pp : t Fmt.t

Error Helper Pattern

let err_api code fields = Error (`Api (code, fields))
let err_parse msg = Error (`Json_parse msg)

let find_user_id json =
  match Yojson.Safe.Util.find_opt "id" json with
  | Some (`String id) -> Ok id
  | Some _ -> err_parse "Expected string for user ID"
  | None -> err_parse "Missing user ID"

Rules

• Never use try ... with _ -> .... Match specific exceptions.
• For unrecoverable startup errors, use Fmt.failwith:

let tls_config =
  match Tls.Config.client ~authenticator () with
  | Ok config -> config
  | Error (`Msg msg) -> Fmt.failwith "Failed to create TLS config: %s" msg

Function Design

• Keep functions small: One function, one purpose. Decompose complex logic.
• Avoid deep nesting: More than 2-3 levels of match/if signals need for refactoring.
• Prefer purity: Isolate side-effects at edges (bin/, lib/ui/).
• Composition over abstraction: Favor small concrete functions over deep abstractions.
• Data-oriented: Operate on simple, immutable data structures.
• No premature generalization: Solve the problem at hand, avoid unnecessary complexity.

Logging

Use the logs library with per-module log sources:

let log_src = Logs.Src.create "project_name.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)

Log Levels

| Level | Use Case | |-------|----------| | Log.app | Messages always shown to user (startup) | | Log.err | Handled but critical errors | | Log.warn | Potential issues, operation continues | | Log.info | Informational state messages | | Log.debug | Verbose debugging details |

Structured Logging

Log.info (fun m ->
    m "Received event: %s" event_type
      ~tags:(Logs.Tag.add "channel_id" channel_id Logs.Tag.empty))

Naming Conventions

| Element | Convention | Example | |---------|------------|---------| | Files | lowercase_underscores | user_profile.ml | | Modules | lowercase_underscores | user_profile | | Primary type | t | type t | | Identifiers | id | type id = string | | Values | short_descriptive | find_user, create_channel |

Labels

Use labels only when they clarify meaning. Avoid ~f and ~x.

CLI Applications

For bin/ applications using cmdliner:

• Place shared functionality (auth, logging setup) in bin/common.ml
• Provide a shared run function that initializes the main loop and environment (e.g., Eio loop)
• All commands should use this function for consistent environment

Commit Messages

Follow Conventional Commits:

Format: type(scope): subject

| Type | Purpose | |------|---------| | feat | New feature | | fix | Bug fix | | docs | Documentation | | style | Formatting | | refactor | Code restructuring | | test | Tests | | chore | Maintenance |

Examples:

• feat(api): add support for file uploads
• fix(ui): correct channel list rendering bug
• test(user): add tests for user profile updates