Code Guidelines

Contributions follow the style of the code around them.

Luwu no longer syncs with upstream Luau. When we want a feature or fix from upstream, we pick it out and port it by hand so Luwu's behavior and optimizations stay intact. Don't reformat code that came from upstream: its original formatting makes it easier to compare against Luau when porting a change.

C++

• Allman braces: an opening brace goes on a separate line.
• Four spaces per indent, never tabs.
• Lines up to 150 columns. Going a little over is fine when breaking the line would read worse.
• A function whose parameters don't fit on one line gets one parameter per line.
• No complex ternaries. When the condition needs more than a glance or the branches span lines, use if/else and give a complicated condition a named bool.
• lowerCamelCase for variables and functions, PascalCase for types and enums, kCamelCase for global constants and SCREAMING_SNAKE_CASE for macros. The VM follows Lua's conventions instead, with lua_ and luaX_ prefixes.

LuauClass* luaR_newclass(
    lua_State* L,
    TString* name,
    uint32_t numberofinstancemembers,
    uint32_t numberofstaticmembers,
    bool hasmemberdefaults
)

Luwu comment tags

Code and comments that change behavior or document a Luwu design decision get a tag:

• // Luwu <Feature> (<doc path>): for a feature with an RFC, like // Luwu Classes (rfcs/classes):. The feature name is in Title Case and matches the RFC's title. A feature named after an API uses the API's spelling: // Luwu table.drop (rfcs/table-drop.md):.
• // Luwu <Description>: for a concept that needs no design doc.
• // Luwu: for a one-off difference from upstream.

Reuse a feature's existing tag, and never use a flag's name as a tag. To sign a comment so tools and other editors leave it alone, write // name <optional@email>: comment with a blank line or code between it and other comments.

Luwu

• Four-space indents, never tabs, and no single-line statements.
• snake_case for locals, functions and methods, and PascalCase for classes, traits and types.
• const for anything that isn't reassigned, functions included.
• Real types instead of any: give a value its type, or use unknown and refine it.
• Flat loops: fold a condition into the loop with when, or move a nested loop into a function.
• Doc comments use --- or --[=[ ]=]. Plain -- comments are for inside a body.

Luau code in the repository may follow StyLua's conventions, but that isn't required.

Rust and Python

• Rust follows rustfmt's defaults.
• Python uses the Black formatter. New scripts should be written in Luwu instead, and existing Python scripts will move to Luwu over time.

Writing

Comments, docs and commit messages say what something is for in plain sentences. A commit subject is type(scope): message, like fix(analysis): ....