Code Formatter

Code Formatter

Formatting rules that optimise for one thing: the next reader locating a function's control-flow exits and its async phase transitions in a single scan. They deliberately diverge from what gofmt, dart format, black and google-java-style produce in specific places, which each rule names.

When to activate

• Writing a new source file in Dart, Java, Python, Kotlin, TypeScript or Go
• Editing a file already written in this style
• Reviewing a branch or pull request and flagging readability problems
• Deciding whether a comment or a doc comment should exist at all

When not to activate

• Naming, SOLID, immutability, error handling and architecture, use coding-standards
• Language-specific idiom and typing in Java, use java-coding-standards
• Language-specific idiom and typing in Python, use python-patterns
• Language-specific idiom in Go, use golang-patterns
• Auto-formatting an unrelated file the project has not adopted this style for
• Human-facing markdown rather than source code, use markdown-writer

The rules

Each rule below has its full body, its reasoning, and its wrong-and-right forms per language in rules-by-language.md. Open that file before applying one you are unsure about.

What the rules look like together

Pass:

public Optional<Receipt> settle(Order order) {
    if (order.isEmpty()) {
        return Optional.empty();
    }

    var total = pricing.total(order);
    var payload = mapper.toPayload(order, total);

    var response = paymentClient.send(payload);

    logger.info("settled order {}", order.id());

    return Optional.of(Receipt.from(response));
}

Fail:

public Optional<Receipt> settle(Order order) {
    if (order.isEmpty()) return Optional.empty();
    var total = pricing.total(order); // price it
    var payload = mapper.toPayload(order, total);
    var response = paymentClient.send(payload);
    logger.info("settled order {}", order.id());
    return Optional.of(Receipt.from(response));
}

The failing version is what most default formatters produce and leave alone. Nothing in it is wrong to a compiler. It is harder to read because the exit, the network call and the return all sit at the same visual weight as the local arithmetic around them.

What this skill does not cover

• Naming conventions, member ordering and import ordering, which vary per language. Use the language style guide and coding-standards
• Line length caps, which stay readable by extracting locals rather than wrapping. Each project sets its own budget
• Trailing commas, brace placement and indent width, which the default formatter for each language owns and this skill does not override

Related skills

• coding-standards owns the engineering floor: SOLID, DRY, KISS, YAGNI, naming, error handling, architecture
• java-coding-standards owns Java idiom, Lombok, Optional, streams and Javadoc discipline
• python-patterns owns Python idiom, typing and package layout
• golang-patterns owns Go idiom and error conventions
• dart-flutter-patterns owns Dart and Flutter structure above the level of a function body
• code-reviewer owns the review pass where these rules get applied to somebody else's diff

Checklist

• No control-flow exit shares a line with its condition
• Blank lines mark the try, the async hand-off and the terminating call as distinct beats
• Every comment sits above the line it describes
• Every doc comment that survived is justified, five prose lines or fewer, one line per tag
• No two consecutive blank lines inside a function body
• Fluent chains break before each dot
• Single-expression bodies were left on one line
• The file was already in this style, or the user asked for the conversion