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.
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 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) { ... }
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) { ... }
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 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;
}
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:
Omit type annotations when:
// 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 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.
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) { ... }
@pUse @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) {
...
}
@rUse @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", "*");
...
}
/**
* 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;
}
| 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 |
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 {
...
}
A typical .aus file follows this order:
/* ... */)include statements/*
* 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.
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);
Use /* ... */ for multi-line non-documentation comments, such as license headers or temporarily disabling a section of code.
Use /** ... */ (Aussom-Doc) only for class, member, and function documentation. Use // or /* */ for inline implementation notes.
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();
| 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) |
