From boxlang-agent-skills
Use this skill when writing, reviewing, or improving BoxLang code to ensure it follows community best practices for naming, structure, scoping, error handling, performance, and maintainability.
How this skill is triggered — by the user, by Claude, or both
Slash command
/boxlang-agent-skills:best-practicesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
BoxLang is a modern dynamic JVM language. These best practices reflect idiomatic
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.
| Item | Convention | Example |
|---|---|---|
| Variables | camelCase | userProfile, orderTotal |
| Functions/Methods | camelCase | getUserById(), processOrder() |
| Classes | PascalCase | UserService, OrderProcessor |
| Constants | UPPER_SNAKE_CASE | MAX_RETRIES, DEFAULT_TIMEOUT |
| Files (classes) | PascalCase | UserService.bx |
| Files (templates) | camelCase or kebab-case | userProfile.bxm, order-details.bxm |
| Files (scripts) | camelCase | buildReport.bxs |
// Good
class UserService {
function getUserById( required numeric id ) {
var MAX_RETRIES = 3
var userId = arguments.id
return userRepository.find( userId )
}
}
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
}
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:
| Instead of | Use |
|---|---|
var session = ... | var sessionData, var userSession, var sess |
var request = ... | var requestData, var req, var httpRequest |
var url = ... | var urlParts, var currentUrl, var uri |
var form = ... | var formData, var formFields, var payload |
var application = ... | var appConfig, var appData, var settings |
var cgi = ... | var cgiData, var serverInfo |
var thread = ... | var threadInfo, var workerThread |
var server = ... | var serverInfo, var hostConfig |
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 ]
}
// BAD — no type information
function processOrder( order, userId ) { ... }
// GOOD — self-documenting, validated at runtime
function processOrder( required struct order, required numeric userId ) {
...
}
// Hard to read
createUser( "John", "Doe", "[email protected]", true )
// GOOD — named arguments document intent
createUser(
firstName = "John",
lastName = "Doe",
email = "[email protected]",
active = true
)
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" )
}
// 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
}
cffinally for Cleanuptransaction {
try {
updateOrder( order )
chargePayment( payment )
transactionCommit()
} catch ( any e ) {
transactionRollback()
rethrow
}
}
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()
}
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 ) )
Prefer literal syntax over constructor functions:
// GOOD — literal syntax
var user = {
name: "Alice",
email: "[email protected]",
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"
=]
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#"
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
}
}
Each .bx class should have one primary purpose. Avoid "god objects" that
handle unrelated concerns. Split into service, repository, and model layers.
application scope for
shared read-only data; invalidate on change.trustedCache=true in production — prevents disk I/O on class
file checks.each() / map() / filter() over manual loops for
collection work — more readable and JIT-friendly.runAsync defaults) for I/O-bound async work;
use fixed-pool executors for CPU-bound work./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
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Unscoped vars in functions | Variables bleed into component scope | Always use var |
Shadowing scope names (session, url, form, etc.) | Breaks access to built-in scopes | Use descriptive names like sessionData, formData |
Silent catch-all catch(any) | Swallows unexpected errors | Re-throw unknown exceptions |
| Logic in templates | Hard to test, poor separation | Move to services/handlers |
| Direct SQL in handlers | No reuse, SQL injection risk | Use repository classes with parameterized queries |
| Storing secrets in code | Security risk | Use environment variables via ${env.VAR_NAME} in config |
Overusing application scope | Concurrency bugs | Use proper locking (bx:lock) for writes |
arr[ 0 ] (zero-based index) | ArrayIndexOutOfBoundsException | BoxLang arrays are 1-indexed: use arr[ 1 ] or arr.first() |
Trailing ; on statements | Noisy / inconsistent style | Semicolons are optional on statements — omit them |
cfheader() / <cfabort> | CFML syntax, not BoxLang | Use bx:header, bx:abort, etc. |
| Named args on Java objects | Not supported, throws runtime error | Always use positional arguments for Java method calls |
createObject("java","path") per call | Verbose, repeated boilerplate | import java:fully.qualified.Class once, then use the class name directly |
BoxLang evolved from CFML but uses different syntax for many constructs. Do NOT
use cf-prefixed tags or functions in BoxLang source files.
| CFML | BoxLang Equivalent |
|---|---|
cfheader(name="X", value="Y") | bx:header name="X" value="Y"; |
cflocation(url="...") | bx:location url="..."; |
cfabort | bx:abort; |
cfparam name="x" default="" | bx:param name="x" default=""; |
cfinclude template="f.cfm" | bx:include template="f.bxm"; |
<cfsilent> | bx:silent { ... } |
createObject("java","path.Class") | import java:path.Class then new java:path.Class() |
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 ] )
}
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
npx claudepluginhub ortus-boxlang/skills --plugin boxlang-agent-skillsProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.