Style Guide

Naming Conventions

File Structure

For large projects, follow the one-type-per-file convention:

src/
  main.br              # Entry point
  user.br              # struct User { ... }
  user_profile.br      # struct UserProfile { ... }
  auth.br              # fn login(), fn register()
  utils/
    math.br            # Math helpers
    string.br          # String utilities
  models/
    llm.br             # Model definitions
    layer.br           # @layer structs

Each file should focus on a single responsibility. Small projects can group related definitions in one file.

Import Ordering

Group imports in order: standard library first, then third-party, then local modules. Separate groups with blank lines:

import std.io;
import std.math;
import std.time;

import bond;
import merge;

import models.llm;
import utils.math;

Comment Style

• Single-line comments: Use // for all inline and line-level comments
• Documentation comments: Use /// for function/module documentation (future doc-gen support)
• Block comments: Use /* */ only for temporarily disabling code blocks
• Hash comments: # is also supported for single-line comments (script compatibility)

/// Compute the average of an array.
/// Returns nil if the array is empty.
fn compute_average(values: [int]) {
    // Guard against empty input
    if values.length == 0 {
        return nil;
    }
    /* Block comment for disabled debugging:
    print("computing average...");
    */
    let sum = 0;
    // ... computation
}

Maximum Line Length

Hard limit at 100 characters. Soft limit at 80 characters for readability. Break long lines at logical points:

// ✓ Good: broken at logical boundary
let result = some_function(
    arg1, arg2, arg3,
    arg4, arg5
);

// ✗ Avoid: exceeding 100 chars
let result = some_function(arg1, arg2, arg3, arg4, arg5, arg6);