Code Styling and Formatting Standards

[Rongmario]

Summary

Introduces standardized code styling and formatting rules for CleanroomMC projects. It aims to ensure consistency across all code contributions by leveraging automated tools like Spotless, Checkstyle, and .editorconfig. These standards will apply to Java source files, Gradle scripts, JSON files, and other relevant formats.

Goals

• Establish consistent formatting across the entire organization and codebase.
• Reduce diffs and merge conflicts caused by style inconsistencies.
• Automate style enforcement through tooling, IDE and CI integration.
• Provide clear guidance and editor support for contributors.

Non Goals

• Refactor existing logic for stylistic reasons alone.

Motivation

Inconsistencies in formatting make code harder to read, maintain, and review. As we grow and accept more contributions, shared standard helps enforce clean and readable code. Automating these rules eliminates style debates during code review. We can get those debates out of the way right now...

Description

Java

• Formatter: Spotless using Eclipse's code formatter xml
• Standards:
  • 4-space indentation
  • 180-character line length
  • Required import ordering
  • Perhaps also adopt Palantir's style since it is lambda friendly

JSON and Other Text Formats

• JSON: 2-space indent, trailing newline, no trailing commas
• Markdown/YAML/TOML: standardized whitespace and indentation
• .editorconfig included to align formatting in all editors

Tooling & Workflow

• Add Spotless to build.gradle

• Add .editorconfig to the root of the project

• Include a GitHub Actions CI check for formatting and style validation

• Add an appropriate CONTRIBUTING.md

• A basis of a spotless block as follows:

spotless {
    encoding 'UTF-8'

    // Format common text files
    format('misc') {
        target '*.gradle', '.gitattributes', '.gitignore', '*.properties', '*.md', '*.yml', '*.toml'
        indentWithSpaces(2)
        trimTrailingWhitespace()
        endWithNewline()
    }

    // Format Java sources using Eclipse
    java {
        eclipse('4.26').configFile('../cleanroom_format.xml') // Shared formatter config
        removeUnusedImports()
        importOrder('java', 'javax', 'net.minecraft', 'com.mojang', '', 'com.cleanroommc', '')
        formatAnnotations()
        indentWithSpaces(4)
        trimTrailingWhitespace()
        endWithNewline()
    }

    // Format JSON files with 2-space indent (more common)
    json {
        target 'src/**/*.json'
        simple().indentWithSpaces(2)
    }
}

• TBD: Eclipse XML (come back later for this!)

Dependencies

• Spotless Plugin
• GitHub Actions
• Editors supporting .editorconfig

References

• Palantir Java Style Guide
• EditorConfig Specification
• Spotless Specification

Guidelines

• I have and will continue to adhere to the guidelines

[ZZZank]

Draft standards look decent, though I still have some questions

• Will 180 line length be too long for Java codes? I myself prefer a shorter line length, for example 120, so that there wont be too much information in one line.
• Will there always be a linebreak before braces? The original Forge code style will always break before braces:

public void someFn()
{
    // code here
}

I myself prefer:

public void someFn() {
    // code here
}

as it makes the whole structure look more unified, and less like two separate structures (declaration and code body) glued together.

This, combined with shorter line length, should be able to keep how many lines a group of codes will require roughly the same as the original Forge style.

• Is braces required for code blocks with only one line? This affects code blocks in while, for, if, etc.

The most common style I saw in current source code:

if (someCondition) someCode;

and a less common style:

if (someCondition)
    someCode;

I myself prefer:

if (someCondition) {
    someCode;
}

as it's more consistent with other code block handling.

[ZZZank]

Personally, I don't see the point of limiting line length at all; it just makes styling more complex. Considering any code editor or IDE out there has a soft line wrap that can be adjusted exactly to your own preference

Line wrap from IDE itself will make some lines long enough be displayed in an odd way, and make lines "extra long enough" a completely solid code rectangle:

line wrap from IDE:

line length limited by formatter:

another example:

[Rongmario]

If selecting an existing format, palantir-java-format is better than google's, the line wrapping is lambda friendly.

I hate capping characters per line, but in projects it's probably the right thing to do, IDE's soft wraps can produce weird results like shown above.

[Desoroxxx]

Will those caps be applied to patches were it is better to do everything we need to in the least number of lines?

[Rongmario]

General consensus is not to do too much in patches, patches dev will be split into a subproject, so it is possible to not apply spotless at all, or use targetExclude in spotless for the same purpose.

[Ecdcaeb]

General consensus is not to do too much in patches, patches dev will be split into a subproject, so it is possible to not apply spotless at all, or use targetExclude in spotless for the same purpose.

I hope the format could be applied for decompile result. An decompile source could pass the format check. Any we dont check the format for cleanroom subproject.