Code Formatting Analysis and Recommendations

[brandbarr]

Summary

I did some analysis in this repo and wanted to report on the inconsistent code formatting in the fflib-apex-common codebase and propose solutions based on community requests in issues #277 and #491.

Current State Analysis

I analyzed all 32 .cls files and found significant formatting inconsistencies across the codebase. Out of 8,933 indented lines total, 6,588 lines (73.7%) use tab indentation while 2,345 lines (26.3%) use space indentation.

The most inconsistent files include fflib_SObjectUnitOfWork.cls with 32% tabs and 67% spaces, fflib_SObjectSelector.cls with only 5% tabs, and fflib_SecurityUtils.cls with just 4% tabs. Meanwhile, most test files use 100% tabs consistently.

The codebase currently follows a modified K&R style with opening braces on the same line as declarations, 4-character indentation (mixing tabs and spaces), and some inconsistent brace placement throughout.

Proposed Solutions

I see two main approaches we could take:

The minimal change approach would be adding EditorConfig only. This is non-invasive since it doesn't reformat existing code, but prevents future inconsistencies and works across all editors. This directly addresses issue #277.

The complete solution would combine EditorConfig with Prettier. This addresses both issues #277 and #491, provides automatic code formatting, enforces consistent style across all files, and integrates well with CI/CD pipelines. The downside is it requires a one-time mass reformatting and adds the prettier-plugin-apex dependency.

For EditorConfig, the implementation would look like:

[*.{cls,apex,trigger}]
indent_style = tab
indent_size = 4
tab_width = 4
end_of_line = lf
insert_final_newline = false

[*.json]
indent_style = space 
indent_size = 2

For Prettier, the configuration would be:

{
  "printWidth": 120,
  "tabWidth": 4,
  "useTabs": true,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "endOfLine": "lf",
  "plugins": ["prettier-plugin-apex"],
  "overrides": [
    {
      "files": "*.{cls,apex}",
      "options": {
        "parser": "apex"
      }
    }
  ]
}

Impact Analysis

I've created both configuration files to demonstrate the approach. When applied to all 38 files, the reformatting resulted in 5,676 insertions and 5,883 deletions (net -207 lines due to whitespace cleanup). The changes include consistent tab indentation throughout, standardized brace placement, consistent quote usage, and removal of trailing whitespace.

The style comparison shows the difference between the current mixed approach and the proposed consistent formatting:

Current mixed style:

public class Example
{
    private String value;
    
    public Example(String val) {
        this.value = val;
    }
}

Proposed consistent style:

public class Example {
	private String value;
	
	public Example(String val) {
		this.value = val;
	}
}

Questions for Discussion

I'd like to get maintainer/community feedback on several key points:

• Should we add EditorConfig to standardize editor behavior going forward?
• Are you interested in automatic code formatting via Prettier?
• Would a one-time formatting pass be acceptable for consistency?
• Do you have any concerns with the proposed K&R variant style?
• Should formatting checks become part of the PR process?

Migration Approach

If we move forward, I'd suggest a phased approach:

• First, add EditorConfig with no code changes for immediate benefit on new code
• Second, add Prettier configuration and format the existing codebase
• Third, add formatting checks to the CI/CD pipeline
• Finally, update contributor guidelines to reflect the new standards

Contribution Offer

I'm happy to volunteer for the implementation work on whichever approach you prefer. I can handle:

• EditorConfig setup
• Fine-tune Prettier configuration based on your preferences
• Manage the mass reformatting across all files
• Implement GitHub Actions workflow for format checking
• Update documentation and contributor guidelines
• Ensure formatting changes don't break functionality

This would address the long-standing formatting inconsistencies while providing modern developer tooling for consistent code quality without creating additional burden for the maintenance team.

Broader Ecosystem Consideration

This formatting standardization should ideally be applied across all apex-enterprise-patterns repositories to maintain consistency throughout the entire ecosystem. The same EditorConfig and Prettier configurations could be implemented in:

• fflib-apex-mocks
• fflib-apex-common-samplecode
• Other related repositories in the apex-enterprise-patterns organization

This would ensure a consistent developer experience and code style across all related projects.

[brandbarr]

It might also be worth considering PMD for static code analysis. PMD can catch potential issues like unused variables, overly complex methods, and other code quality concerns that complement formatting standards. This would provide a more comprehensive code quality solution alongside the formatting tools.