OCaml Conventions

ocamlfunctionalbackend

Conventions for writing idiomatic OCaml covering module system usage, functors, pattern matching, error handling with Result, and build system conventions with Dune.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# OCaml Conventions ## Module System - Every `.ml` file defines a module. Use `.mli` interface files to define the public API of each module. - Always write `.mli` files for library modules — they serve as the explicit API contract. - Use uppercase `CamelCase` for module names. File `user_service.ml` defines module `User_service` (auto-capitalized by the compiler; rename with Dune's `(name ...)` if needed). - Use nested modules for related subcomponents: `module User = struct ... end` inside larger modules. - Open modules sparingly and only at the top of `.ml` files: `open Core`. Never use `open` in `.mli` files. ## Functors - Use functors to parameterize modules over types or behaviors: `module Make (Repo: REPO_SIG) : SERVICE_SIG = struct ... end`. - Define module signatures (interfaces) as module types: `module type REPO_SIG = sig ... end`. - Name functor signatures with `_SIG` suffix. Name functor modules with `Make` prefix. - Prefer functors over global mutable state for dependency injection. ## Pattern Matching - Always use exhaustive pattern matching. Enable `-warn-error +8` to treat incomplete patterns as errors. - Use `match` over `if/else` for more than 2 branches. - Destructure records and tuples in pattern match arms directly: `| { id; name; _ } -> ...`. - Use wildcard `_` only for intentionally ignored fields — never for catching all cases in a match. - Use `when` guards sparingly — prefer separate match arms for clarity. ## Error Handling - Use `Result.t` (`Ok value | Error err`) for recoverable errors in application code. - Define error types as descriptive sum types: `type error = Not_found | Invalid_input of string | Db_error of string`. - Use `let*` (bind operator from `Result` monad) for chaining fallible operations cleanly. - Use exceptions only for truly exceptional conditions (programmer errors, unrecoverable IO failures). - Never use exceptions for control flow. Do not catch exceptions in business logic code. - Convert exception-throwing library functions to `Result`-returning wrappers at module boundaries. ## Types & Values - Prefer immutable data. Use `let` bindings, not `ref` mutable cells, unless mutation is necessary. - Use record types for structured data: `type user = { id: int; name: string; email: string }`. - Use variant types (sum types) for disjoint states: `type status = Active | Inactive | Suspended of string`. - Use `option` for truly optional values; use `Result` when absence is an error condition. - Prefer labeled arguments for functions with multiple same-type parameters: `let create ~id ~name () = ...`. ## Naming Conventions - Values and functions: `snake_case`. - Types: `snake_case` (e.g., `user_id`, `order_status`). - Modules and type constructors: `CamelCase` (e.g., `UserService`, `NotFound`). - Module types (signatures): `SCREAMING_SNAKE_CASE` (e.g., `USER_SERVICE`, `REPO`). - Boolean functions: `is_*` or `has_*` prefix (e.g., `is_valid`, `has_permission`). ## Dune Build System - Use Dune for all builds. Define `dune` files in every directory that contains buildable files. - Use `(library ...)` for shared code, `(executable ...)` for runnable programs, `(test ...)` for tests. - Specify `(libraries ...)` explicitly — list all direct dependencies; do not rely on transitive exposure. - Pin library versions in `dune-project` using `(depends ...)` with `(>= version)` constraints. - Use `(ocamlopt_flags (:standard -O2 -unbox-closures))` for performance-critical libraries. ## Formatting & Style - Use `ocamlformat` for consistent formatting. Commit a `.ocamlformat` config file with `profile = conventional`. - Run `ocamlformat --check` in CI to enforce formatting. - Maximum line length: 100 characters. ## Anti-Patterns - Do not use `Obj.magic` — it bypasses the type system and causes undefined behavior. - Do not use `Hashtbl` mutably when a functional `Map` would suffice. - Do not write `.ml` files without corresponding `.mli` for library code — it exposes all internals. - Do not use `Printf.printf` for application logging — use a structured logging library.

CLI

npx mindaxis apply ocaml-rules --target cursor --scope project

Используется в паках

Не используется ни в одном паке

← Правила