moonbit-bestpractice（Moonbit 最佳实践）

MoonBit Coding Standards

Related Skills

• moonbit-docs — MoonBit language reference (syntax, types, functions, methods, deriving). Use for language questions and debugging.

1. Documentation

• Use ///| for documentation comments on top-level definitions (functions, structs, enums, traits, tests). This is the output format of moon fmt.
• Ensure public APIs are documented.

2. Naming Conventions

• Types (Structs, Enums) & Traits: PascalCase (e.g., Position, GeoJSONObject, ToBBox).
• Abbreviations: Abbreviations other than those at the beginning (such as JSON or ID) should generally be all uppercase (e.g. FromJSON, JSONToMap).
• Functions & Methods: snake_case (e.g., from_json, to_geometry, boolean_point_in_polygon).
• Variables & Parameters: snake_case (e.g., coordinates, shifted_poly).
• No Abbreviations: Do not abbreviate variable names unless they are common abbreviations (e.g., id, json). Avoid p for point, ls for line_string, etc.
• Collections: Use the _array suffix for array arguments/variables instead of plural names (e.g., polygon_array instead of polygons).
• Constructors: Always define fn new inside the struct body. Factory functions use new_hoge/from_hoge naming — never ::new.

3. Idioms & Best Practices

3.1 Constructors & Instance Initialization

• Default constructor: The fn new declaration inside the struct body is the constructor definition itself — do NOT write a separate fn StructName::new(...) implementation outside. fn new supports raise, so validation logic should be placed in new to ensure instances are always in a valid state. OK: struct MyStruct {x: Int y: Int fn new(x~: Int, y~: Int) -> MyStruct} NG: fn MyStruct::new(x~: Int, y~: Int) -> MyStruct {{x, y}}
• Factory functions: Define separate static functions with names like new_hoge, from_hoge, etc. Never name them ::new. Factory functions must generate values via the new constructor (StructName(...) is equivalent to StructName::new(...)): struct Rect {x: Double y: Double width: Double height: Double // Validation in new ensures all Rect instances have valid size fn new(x~: Double, y~: Double, width~: Double, height~: Double) -> Rect raise} // Conversion: create from a different representation fn Rect::from_corners(x1~: Double, y1~: Double, x2~: Double, y2~: Double) -> Rect {Rect(x=x1, y=y1, width=x2 - x1, height=y2 - y1)} // Specific state: create a type with optional fields in a predetermined state fn Rect::new_unit(x~: Double, y~: Double) -> Rect {Rect(x~, y~, width=1.0, height=1.0)}
• Initialization: Struct literal syntax (StructName::{...}) should ONLY be used strictly within constructor functions like new. External code must use the constructor syntax (StructName(...)).
• Updating: Use dedicated update functions/methods to modify values.
• Struct Update Syntax: Avoid using Struct Update Syntax (e.g., {..base, field: value}) whenever possible, as it may bypass validation logic or constraints.
• Ignore Usage: Use proper pipeline style when ignoring return values: expr |> ignore.

3.2 Error Handling

Use the raise effect for functions that can fail instead of returning Result types for synchronous logic.

Defining error types:

suberror DivError { DivError(String) }

suberror E3 {
  A
  B(String)
  C(Int, loc~ : SourceLoc)
}

suberror uses enum-like constructor syntax. The older suberror A B syntax is deprecated. Always use suberror A {A(B)} with explicit constructors.

Raising errors:

• Custom error: raise DivError("division by zero")
• Generic failure: fail("message") — convenience function that raises Failure type with source location

Function signatures:

fn div(x : Int, y : Int) -> Int raise DivError { ... }

fn f() -> Unit raise { ... }

fn add(a : Int, b : Int) -> Int noraise { a + b }

• raise CustomError: function may raise a specific error type
• raise or raise Error: function may raise any error
• noraise: function guaranteed not to raise

Handling errors:

try div(42, 0) catch {
  DivError(msg) => println(msg)
} noraise {
  v => println(v)
}

let a = div(42, 0) catch { _ => 0 }

let res = try? (div(6, 0) * div(6, 3))

try! div(42, 0)

• try {expr} catch {pattern => handler} noraise {v =>...}: full error handling
• let a = expr catch {_ => default}: simplified inline catch
• try? expr: convert to Result[T, Error]
• try! expr: panic on error

Error polymorphism:

Use raise? for higher-order functions that conditionally throw:

fn[T] map(
  array : Array[T],
  f : (T) -> T raise?
) -> Array[T] raise? { ... }

When f is noraise, map is also noraise. When f raises, map raises.

Best practices:

• Prefer raise effect over Result for synchronous code
• In tests, let errors propagate or use guard to assert success

3.3 Pattern Matching & Guards

• Avoid if for Validation: Use guard instead: guard array.length() > 0 else {raise Error("Empty")}
• Use guard for assertions, early returns, or unwrapping:

- General Code: Always provide an explicit fallback using else: guard hoge is Hoge(fuga) else {raise fail("Message")} - Tests: Use guard without fallback for better readability: guard feature.geometry is Some(@geojson.Geometry::Polygon(poly))

• Use match for exhaustive handling of Enums.
• Use Labeled Arguments/Punners (~) in patterns and constructors when variable names match field names: match geometry {Polygon(coordinates~) => coordinates}

3.4 Functions

• Anonymous Functions: Prefer arrow syntax args => body over fn keyword fn(args) {body}.
• Local fn annotation: Local fn definitions must explicitly annotate raise/async effects. Inference for local fn is deprecated. Arrow functions are unaffected. fn outer() -> Unit raise {fn local_fn() -> Unit raise {fail("err")} let arrow_fn = () => {fail("err")}}

3.5 Structs & Enums

• Enum Wrapping Structs: Define independent Structs for each variant, then wrap them in the Enum. Use the same name for the Variant and the Struct. pub struct Point {...} pub enum Geometry {Point(Point) MultiPoint(MultiPoint)} derive(Debug, Eq)
• Delegation: When implementing traits for such Enums, pattern match on self and delegate to the inner struct's method.
• Prefer distinct Structs for complex data wrapped in Enums if polymorphic behavior is needed.
• Standard traits: Debug, Eq, Compare, ToJson, FromJson, Hash (note: types containing Json cannot derive Hash).
• Debug trait: Always derive Debug instead of Show. Debug replaces Show as the standard trait for structural formatting. Uses debug_inspect() for output. struct MyStruct {...} derive(Debug, Eq)
• Constructor qualified names: Built-in constructors require qualified names (e.g., Failure::Failure). Constructors with arguments cannot be used as higher-order functions; use a wrapper: let f = x => Some(x)

3.6 Traits

• Definition Notation: pub trait ToGeoJSON {to_geojson(Self) -> GeoJSON}
• Performance Overrides: Always override default trait methods if a more efficient implementation is possible for the specific type.
• Implementation Rules:

1. Default Implementation: If a method's return value is not Self and it can be implemented solely using other methods, provide a default implementation. 2. Trait Object Delegation: When implementing a super-trait for a type that also implements a sub-trait, define the logic as a static function on the sub-trait's object and relay to it. 3. Direct Implementation: If delegation is not possible or creates circular dependencies, implement the method directly on the type.

3.7 Cascade Operator

x..f() is equivalent to {x.f(); x} — for methods returning Unit.

let result = StringBuilder::new()
  ..write_char('a')
  ..write_object(1001)
  ..write_string("abcdef")
  .to_string()

Enables chaining mutable operations without modifying return types. Compiler warns if result is ignored.

3.8 Range Syntax

• a..<b: exclusive upper bound (increasing)
• a..<=b: inclusive upper bound (increasing) — replaces deprecated a..=b
• a>..b: exclusive lower bound (decreasing)
• a>=..b: inclusive lower bound (decreasing)

for i in 0..<10 { ... }
for i in 10>=..0 { ... }

3.9 Loop nobreak

Replaces old loop else. Executes when the loop condition becomes false.

let r = while i > 0 {
  if cond { break 42 }
  i = i - 1
} nobreak {
  7
}

break must provide a value matching the nobreak return type.

3.10 declare Keyword

Similar to Rust's todo! macro. Use declare before function definitions to indicate specification-only declarations. Missing implementations generate warnings (not errors).

declare fn add(x : Int, y : Int) -> Int

4. Performance Optimization

• Lazy evaluation with Iterator: For array processing where the size is unknown or potentially large, prefer iter() for lazy evaluation to avoid intermediate array allocations. This is especially effective for fold operations like minimum()/maximum(): let min_x = coords.iter().map(c => c.x()).minimum().unwrap()
• Flattening: Use flatten() instead of manual loops with append when merging nested collections.

5. Toolchain

• moon.pkg DSL replaces deprecated moon.pkg.json.

6. Testing

See MoonBit Testing Standards for detailed testing guidelines.