Boxlang Best Practices

BoxLang Best Practices

Overview

BoxLang is a modern dynamic JVM language. These best practices reflect idiomatic BoxLang patterns informed by the language's design, CFML heritage, and JVM performance characteristics. Following them produces code that is readable, maintainable, performant, and safe.

Naming Conventions

// Good
class UserService {
    function getUserById( required numeric id ) {
        var MAX_RETRIES = 3
        var userId = arguments.id
        return userRepository.find( userId )
    }
}

Variable Scoping

Always declare local variables with var inside functions to avoid polluting the variables scope (the component-level scope).

// BAD — leaks into variables scope
function process() {
    result = doWork()
    return result
}

// GOOD — properly local
function process() {
    var result = doWork()
    return result
}

Use explicit scope prefixes when ambiguity exists:

function getUser( required numeric id ) {
    // Explicitly scope to avoid confusion
    var userData = variables.userRepo.find( arguments.id )
    return userData
}

Avoid Shadowing Built-In Scope Names

Never declare local variables with the same name as a built-in scope. BoxLang resolves unscoped variable references by walking the scope chain, and shadowing a scope name breaks access to that scope's data and causes confusing bugs.

Reserved scope names to avoid as variable names: session, server, request, url, form, application, cgi, thread

// BAD — shadows the `session` scope, breaking all session access
function login( required string user ) {
    var session = { user: arguments.user }  // DON'T do this
    session.user = arguments.user           // writes to local var, not session scope
}

// BAD — shadows the `url` scope
var url = parseUrl( input )                 // url.params is now broken

// GOOD — use descriptive names that don't collide
function login( required string user ) {
    var sessionData = { user: arguments.user }
    session.user = arguments.user           // correctly writes to session scope
}

// GOOD — use a different name
var urlParts = parseUrl( input )
var queryParams = url.params                // url scope still accessible

When you need a local reference to scope data, use a name that describes the data, not the scope itself:

Scope Lookup Performance

BoxLang walks the scope chain on each unscoped variable access. In hot code paths (tight loops, high-traffic request handlers), scope your variables explicitly for predictable performance:

// GOOD in hot paths — no scope chain walk
var len = arguments.items.len()
for ( var i = 1; i <= len; i++ ) {
    // process arguments.items[ i ]
}

Functions

Always Declare Argument Types and Required Status

// BAD — no type information
function processOrder( order, userId ) { ... }

// GOOD — self-documenting, validated at runtime
function processOrder( required struct order, required numeric userId ) {
    ...
}

Use Named Arguments for Clarity

// Hard to read
createUser( "John", "Doe", "john@example.com", true )

// GOOD — named arguments document intent
createUser(
    firstName = "John",
    lastName  = "Doe",
    email     = "john@example.com",
    active    = true
)

Return Types

Declare return types for public functions to document contracts and enable better IDE support:

struct function getUser( required numeric id ) {
    return userService.find( arguments.id )
}

array function listActiveUsers() {
    return userService.findByStatus( "active" )
}

Error Handling

Catch Specific Exception Types

// BAD — catches everything, hides bugs
try {
    processOrder( order )
} catch ( any e ) {
    logError( e )
}

// GOOD — handle specific cases, re-throw unknown
try {
    processOrder( order )
} catch ( "Database" e ) {
    handleDatabaseError( e )
} catch ( "Validation" e ) {
    return { success: false, message: e.message }
} catch ( any e ) {
    // Re-throw unexpected errors
    rethrow
}

Use cffinally for Cleanup

transaction {
    try {
        updateOrder( order )
        chargePayment( payment )
        transactionCommit()
    } catch ( any e ) {
        transactionRollback()
        rethrow
    }
}

Null Safety

Use the safe-navigation operator (?.) and Elvis operator (?:) to avoid null pointer errors:

// Null-safe chained access
var city = user?.address?.city ?: "Unknown"

// Null-safe method calls
var count = order?.items?.len() ?: 0

Prefer isNull() over direct comparisons with null:

if ( isNull( result ) ) {
    return getDefault()
}

Closures vs Lambdas

Use lambdas (->) for pure deterministic operations on their arguments only. Use closures (=>) when accessing outer scope variables or calling external functions/BIFs.

// Lambda — only uses the item argument (pure transform)
var doubled = numbers.map( ( n ) -> n * 2 )

// Closure — accesses outer variable `threshold`
var filtered = numbers.filter( ( n ) => n > threshold )

// Closure — calls external BIF
var upper = words.map( ( w ) => uCase( w ) )

Struct and Array Literals

Prefer literal syntax over constructor functions:

// GOOD — literal syntax
var user = {
    name:  "Alice",
    email: "alice@example.com",
    roles: [ "admin", "user" ]
}

// Avoid unless dynamic keys are needed
var user = structNew()
user.name = "Alice"

Use ordered struct literal syntax when key order matters:

// Ordered struct (insertion order preserved)
var config = [=
    host: "localhost",
    port: 5432,
    database: "myapp"
=]

String Interpolation

Use #expression# for interpolation in strings and templates. For complex expressions, assign to a variable first for readability:

// Simple interpolation
var message = "Hello, #user.name#!"

// Complex — extract first
var formattedDate = dateTimeFormat( now(), "long" )
var header = "Report generated on #formattedDate#"

Component (Class) Design

Constructor Pattern

Use init() as the constructor. Return this for fluent construction:

class UserService {

    property name="userRepo" inject="UserRepository"

    function init( required UserRepository userRepository ) {
        variables.userRepo = arguments.userRepository
        return this
    }

}

Keep Classes Focused (Single Responsibility)

Each .bx class should have one primary purpose. Avoid "god objects" that handle unrelated concerns. Split into service, repository, and model layers.

Performance Tips

1. Cache expensive lookups — store results in application scope for shared read-only data; invalidate on change.
2. Use trustedCache=true in production — prevents disk I/O on class file checks.
3. Pre-compute in constructors — if a value won't change, compute it once during instantiation.
4. Prefer each() / map() / filter() over manual loops for collection work — more readable and JIT-friendly.
5. Use virtual threads (runAsync defaults) for I/O-bound async work; use fixed-pool executors for CPU-bound work.

Code Organization

/app
  /models           -- Business domain classes (.bx)
  /services         -- Service layer classes (.bx)
  /repositories     -- Data access classes (.bx)
  /handlers         -- Request handlers / controllers (.bx)
  /views            -- Templates (.bxm)
  /includes         -- Reusable partial templates (.bxm)
  /scripts          -- Standalone scripts (.bxs)
  Application.bx    -- Application lifecycle

Common Anti-Patterns to Avoid

BoxLang vs CFML Quick-Reference

BoxLang evolved from CFML but uses different syntax for many constructs. Do NOT use cf-prefixed tags or functions in BoxLang source files.

Array Best Practices

BoxLang arrays are 1-indexed. This is a common source of bugs for developers coming from Java/JavaScript backgrounds.

var items = [ "a", "b", "c" ]

// CORRECT
var first = items[ 1 ]          // "a"
var last  = items[ items.len() ] // "c"
var first = items.first()        // preferred — more readable
var last  = items.last()         // preferred

// WRONG (throws ArrayIndexOutOfBoundsException)
var first = items[ 0 ]

// Looping — i starts at 1
for ( var i = 1; i <= items.len(); i++ ) {
    process( items[ i ] )
}

Passing Single Values to Java Varargs

Java varargs methods require a BoxLang array, not a bare scalar value:

// CORRECT — wrap in array
storage.query( "SELECT * FROM t WHERE id = ?", [ requestId ] )

// WRONG — bare value is not accepted by Java varargs
storage.query( "SELECT * FROM t WHERE id = ?", requestId )    // throws