Complete Guide to Code Formatting Best Practices

Code formatting debates have ended. Automated formatters like Prettier, Black, and gofmt have made manual formatting decisions irrelevant. But setting up formatting correctly — choosing the right tools, configuring them for your project, and enforcing them in CI — still requires careful thought. This guide covers everything you need.

Why Formatting Matters

Consistent code formatting reduces cognitive load during code review. When every file follows the same style, reviewers focus on logic and architecture rather than indentation and bracket placement. Studies show that consistently formatted codebases have fewer bugs — not because formatting prevents bugs directly, but because it makes code easier to read and reason about.

Formatting also reduces merge conflicts. When two developers format the same code differently, Git sees every reformatted line as a change. Automated formatting ensures that formatting changes happen in a single commit, and subsequent changes only touch lines with actual logic changes.

JavaScript and TypeScript: Prettier

Prettier is the standard JavaScript and TypeScript formatter. It supports JSX, CSS, HTML, JSON, Markdown, YAML, and GraphQL. The key philosophy is minimal configuration — Prettier makes most formatting decisions for you, leaving only a few options like print width, tab width, semicolons, and quote style.

The recommended setup is Prettier for formatting plus ESLint for code quality rules. Install eslint-config-prettier to disable ESLint rules that conflict with Prettier. Run Prettier through eslint-plugin-prettier or as a separate step — both approaches work, but running them separately is faster.

For the format-on-save experience, configure your editor to run Prettier on save. In VS Code, set editor.defaultFormatter to esbenp.prettier-vscode and enable editor.formatOnSave. This gives you instant feedback while coding.

Python: Black and Ruff

Black is the Prettier of Python — an opinionated formatter with minimal configuration. It produces consistent, readable Python code and has become the de facto standard. Ruff is a newer, faster alternative written in Rust that includes both formatting and linting. Ruff is 10-100x faster than Black and is rapidly gaining adoption. For new Python projects, Ruff is the recommended choice.

Both Black and Ruff enforce PEP 8 with their own opinionated decisions on top. The result is Python code that looks the same regardless of who wrote it. Combine with isort (or Ruff built-in import sorting) to keep imports organized.

Go, Rust, and Other Languages

Go solved the formatting problem at the language level with gofmt. Every Go file is formatted identically. There is no configuration, no debate, and no setup beyond installing Go. This approach inspired many other language formatters.

Rust uses rustfmt with a similar philosophy. Zig uses zig fmt. Dart uses dart format. The trend is clear — modern languages ship with a built-in formatter, and the community expectation is that all code is formatted with it.

Enforcing Formatting in CI

The most important step is making formatting a CI check. Add a step to your CI pipeline that runs the formatter in check mode (prettier --check, black --check, ruff format --check) and fails the build if any file is not formatted. This prevents unformatted code from being merged regardless of individual developer editor configurations.

Combine CI checks with pre-commit hooks using Husky (JavaScript) or pre-commit (Python). The hook runs the formatter before each commit, catching formatting issues before they reach CI. Lint-staged runs the formatter only on staged files, keeping the hook fast even in large repositories.

EditorConfig for Cross-Editor Basics

EditorConfig is a simple configuration file (.editorconfig) that sets basic formatting rules — indent style, indent size, end-of-line character, and trailing whitespace — across all editors. It does not replace language-specific formatters but ensures that editors use the correct basic settings. Every project should have an .editorconfig file.

Our Formatting Tools

AIDToolStack provides browser-based formatters for JSON, SQL, HTML, CSS, XML, and YAML. These tools are useful for quick one-off formatting — paste unformatted code, get formatted output, copy it back. For files in your project, always use the project formatter (Prettier, Black, etc.) to ensure consistency with your configuration.