Aussom Language Style Guide

This guide defines the preferred coding conventions for Aussom source files (.aus). Consistent style makes code easier to read, maintain, and document. Where existing code deviates from these rules, prefer the style described here in new or updated code.

Naming Conventions

Class Names — PascalCase

Regular class names use PascalCase: each word begins with a capital letter, no underscores between words.

// Correct
class CharacterParams { ... }
class ResponseObj { ... }
class RegistrationRequest { ... }

// Avoid
class characterParams { ... }
class responseObj { ... }
class registration_request { ... }

Exception — static classes and enums use all lowercase, optionally with underscores. These are singletons or value sets, and the lowercase convention signals that distinction.

// Correct — static class
static class hdata { ... }
static class sys { ... }

// Correct — enum
enum side { ... }
enum accessLevel { ... }

Function Names — camelCase

Function names use camelCase: the first word is lowercase, subsequent words are capitalized.

// Correct
public getCharacterById(Id) { ... }
public handleCharacterGet(Req, Rdata) { ... }
public setCorsHeaders(Req) { ... }

// Avoid
public GetCharacterById(Id) { ... }
public handle_character_get(Req, Rdata) { ... }

Function Definition Arguments — PascalCase

Arguments declared in a function definition use PascalCase. This makes them visually distinct from local variables assigned inside the function body, and from member variables accessed via this.

// Correct
public set(Rec) {
    this.id = Rec.id;
    this.firstName = Rec.firstName;
}

public responseObj(bool Success, string Message) {
    this.success = Success;
    this.message = Message;
}

private handleCharacterGet(Req, Rdata) {
    id = Rdata.queryParams.id;
    ch = hdata.getChById(id);
    ...
}

// Avoid
public set(rec) { ... }
private handleCharacterGet(req, rdata) { ... }

Local Variables — camelCase

Variables assigned inside a function body use camelCase.

public index(Req) {
    con = this.getConnection();
    regRows = [];
    usgLabels = [];

    for (row : regRows) {
        trimmedRow = row[0].trim();
    }
}

Member Variables — camelCase

Member variables declared in the class body (with or without an access modifier) use camelCase.

class Registration {
    public registrationId = "";
    public licenseKey = "";
    public firstName = "";
    public emailAddress = "";

    private dbHost = "localhost";
    private dbPort = 3306;
}

Type Annotations in Function Arguments

Aussom allows optional type annotations on function arguments. When a type is specified, the interpreter enforces it at call time — the caller is responsible for passing the correct type.

Use type annotations when:

Writing library or extern functions where enforcing input types avoids defensive checking inside the body.
The function is public API and incorrect types would produce confusing downstream errors.
Typing provides meaningful self-documentation.

Omit type annotations when:

The function is an internal implementation detail.
The argument type is already clear from context or usage.
The function intentionally accepts multiple types.

// Type annotation used — public API, types enforced by the interpreter
public responseObj(bool Success, string Message) {
    this.success = Success;
    this.message = Message;
}

// No type annotation — internal helper, type is clear from context
private handleCharacterGet(Req, Rdata) {
    id = Rdata.queryParams.id;
    ...
}

Available type keywords for annotations: int, double, bool, string, list, map, object.

Important: Function definitions never specify a return type. There is no return type syntax in Aussom — attempting to add one will produce a syntax error. Use an Aussom-Doc @r tag (see below) to document what a function returns.

// Correct — no return type in the definition
public getCharacterById(string Id) {
    ...
    return ch;
}

// Wrong — will produce a syntax error
// character getCharacterById(string Id) { ... }

Aussom-Doc Comments

Aussom supports a documentation comment format called Aussom-Doc. These comments are parsed by the runtime and can be used by tooling (such as Aussom Server's doc generator) to produce Markdown documentation. Aussom-Doc comments should be used on all public classes, member variables, and functions.

Syntax

An Aussom-Doc comment opens with /** and closes with */. It appears immediately before the class, member, or function it documents.

/**
 * Brief description of what this does.
 */
public myFunction(Arg) { ... }

Documenting Parameters with `@p`

Use @p to document each function argument. The format is:

@p ArgName is a description of the argument.

Each @p tag should be on its own line within the comment. The argument name should match the PascalCase name used in the function definition.

/**
 * Handles the GET /character request.
 * @p Req is the HTTP request object.
 * @p Rdata is the parsed request data as a map.
 */
private handleCharacterGet(Req, Rdata) {
    ...
}

Documenting Return Values with `@r`

Use @r to describe what the function returns. Since Aussom has no return type syntax in the function definition, @r is the only way to communicate the return value to the reader.

/**
 * Creates and returns a MySQL database connection.
 * @r A connected mysql object.
 */
private getConnection() {
    con = new mysql(...);
    con.connect();
    return con;
}

For functions that return null or send a response directly (and return nothing meaningful), document that explicitly:

/**
 * Sets CORS headers on the response.
 * @p Req is the request object.
 * @r null
 */
private setCorsHeaders(Req) {
    Req.putHeader("Access-Control-Allow-Origin", "*");
    ...
}

Full Example

/**
 * Sets the character data from the provided record map.
 * This is used to easily load data from a database row
 * or a deserialized API body.
 * @p Rec is a map containing the character field values.
 * @r this object, to allow chaining.
 */
public set(Rec) {
    this.id = Rec.id;
    this.firstName = Rec.firstName;
    this.lastName = Rec.lastName;
    this.rank = Rec.rank;
    return this;
}

What to Document

Element	Aussom-Doc required?
Public class	Yes
Public member variable	Yes
Public function	Yes
Private function	Recommended for non-obvious logic
Private member variable	Optional
Constructor	Yes if it takes arguments

Class-Level Comments

Place an Aussom-Doc comment directly before the class keyword. If the class also has annotations, the comment goes before the annotations.

/**
 * Standard API response object. Used for both success
 * and error responses.
 */
@ApiRequired
class ResponseObj {
    ...
}

File Structure

A typical .aus file follows this order:

License header (block comment /* ... */)
include statements
Class definitions

/*
 * Copyright 2024 Roseville Code Inc.
 *
 * Licensed under the Apache License, Version 2.0 ...
 */

include file;
include mysql;

/**
 * Main application class.
 */
class MyApp : AppBase {
    ...
}

/**
 * Supporting data class.
 */
class MyDataObj {
    ...
}

Multiple classes in a single file is fine and common — group closely related classes together.

Comments

Single-Line Comments

Use // for single-line comments that explain the intent of the following line or block. Avoid restating what the code already says clearly.

// Get the request data.
rdata = Req.getReq();

// Locate the character by the provided ID.
ch = hdata.getChById(id);

Block Comments

Use /* ... */ for multi-line non-documentation comments, such as license headers or temporarily disabling a section of code.

Aussom-Doc vs Regular Comments

Use /** ... */ (Aussom-Doc) only for class, member, and function documentation. Use // or /* */ for inline implementation notes.

Indentation and Bracing

Use tabs for indentation (consistent with the standard library and existing Aussom Server apps).
Opening braces go on the same line as the declaration or statement.
Closing braces go on their own line.

class CharacterParams {
    public firstName = "";

    public CharacterParams(string FirstName) {
        this.firstName = FirstName;
    }

    public getFirstName() {
        return this.firstName;
    }
}

For short single-statement function bodies (such as extern stubs or trivial constructors), the braces may be on the same line:

public character() { }
public extern getSysInfo();

Summary Table

Element	Convention	Example
Regular class name	PascalCase	`CharacterParams`
Static class name	all lowercase	`hdata`, `sys`
Enum name	all lowercase	`side`, `rank`
Function name	camelCase	`getCharacterById`
Function argument	PascalCase	`Req`, `Success`, `Rdata`
Local variable	camelCase	`con`, `regRows`, `cparams`
Member variable	camelCase	`firstName`, `licenseKey`
Return type	not declared	(use `@r` in Aussom-Doc)