-
Notifications
You must be signed in to change notification settings - Fork 0
Code Formatting and Linting
A code formatter is a program that adjusts written code to match a particular code style, ideally specified in a project configuration file that can be shared among teammates. It helps to standardize code so that it is easier for developers to work with each other's code, and to jump back into old code too.
Much has been written about issues surrounding lack of coding style for teams.
This topic can be confusing — I think because formatting and linting were once more intermixed in tooling. The separation between the two has become a bit more clear, although not entirely.
The goal of formatting is to enhance code readability by creating a consistent visual presentation.
The goal of code linting is to statically analyze code for potential errors, bugs, and style violations. Formally semicolons and naming conventions are part of linting, but formatters may make decisions as well.
Prettier officially recommends only linting for code quality, not for code format. Formatters exist to handle code style; Linters exist to detect unused code, bugs, etc.
| Behavior | Formatting | Linting | Ambiguous |
|---|---|---|---|
| Indentation styles (spaces vs. tabs) | ✔️ | ❌ | |
| Spacing (around operators, commas, extra space) | ✔️ | ❌ | |
| Line length | ✔️ | ❌ | |
| Braces and parenthesis | ✔️ | ❌ | |
| Quotation mark style | ✔️ | ❌ | |
| Semicolons | 🟡 Overlaps both a style convention and possibly errors depending on language/version | ||
| Variable, class, etc. naming conventions (PascalCase, camelCase) | 🟡 Is a style convention, but often requires a linter or static analyzer per the language | ||
| Unused variables | ❌ | ✔️ | |
| Incorrect function parameters | ❌ | ✔️ |
This topic confused me for a long time. A formatter and/or linter may run at various phases in the development cycle:
| Where | Description |
|---|---|
| Developer IDE | Plug-ins and/or built-in features are configured with a team configuration file. 🟢 Easiest way to for humans to manage 🟡 Need to configure 🔴 Only applies to files as they are touched or created, not a whole codebase (unless such tooling exists) — however often formatters/linters will have command line options to format an entire codebase |
| Build | Can be told to fail if there are formatting and/or linting errors. 🟢 Helps to enforce or inform the developer that a formatter/linter failed 🔴 Error messages can be confusing to parse, especially in formatting — this is usually a disaster if the IDE has not also been configured |
| Commit | Similar to build |
| Deploy | Similar to build |
Unopinionated code formatters adopt the philosophy that an individual team is responsible for configuring its code style. This likely derives from when structured and resourced teams would dedicate development time to writing and maintaining a formal code style guide. Writing the guide was one thing — following it was another. An unopinionated code formatter can help teams enforce their code style guide, as they see fit.
🟢 Allows full control, enabling team to determine own code style
🟢 Widely supported across languages and IDEs via Editorconfig, a popular configuration file format
🟡 Formatting tends to be only as aggressive as the team takes time to make it, which can lead to loosely standardized code enforcement
🔴 Need to spend time debating with team about code style, ideally upfront, and this can be an emotional exercise from some developers who have strong opinions
🔴 Time-consuming and detailed configuration that may need to be tweaked over time — changes in development might require many file changes (although a "code cleanup" tool or command line can help do this in a single commit)
A popular opinionated code formatter that is controlled through a config file is Editorconfig.
Editorconfig universally supports a fairly simple set of code standardizations:
indent_style
indent_size
tab_width
end_of_line
charset
trim_trailing_whitespace
insert_final_newline
Additionally, each IDE implementation of Editorconfig might offer more or less support. If the IDE targets a particular stack, such as Visual Studio, you may see domain-specific properties added to the formatter as well. However as of my exploration in 2023, this support may be soft. For example, Microsoft offers good Editorconfig support for C# .cs files, but not C# .razor/.cshtml files. This is an issue in both VS Code and Visual Studio.
Domain-specific properties might look like:
dotnet_style_qualification_for_field = false:silent
dotnet_style_qualification_for_property = false:silent
dotnet_style_qualification_for_method = false:silent
dotnet_style_qualification_for_event = false:silent
🔗 Dotnet Code-style rule options
Opinionated code formatters adopt the philosophy that a larger development community for a language should make decisions surrounding code style. This offloads decision-making (and indecision/arguments) from a resource-strained team and standardizes practices across many development teams. While some options might exist, they are usually limited by design.
🟢 Almost fully offloads coding style from the team's plate
🟢 Tend to sync matching options (limited set) with Editorconfig format
🟢 Aggressive formatting leadings to very standardized code where it is hard to deviate from expectations
🟡 "Flavors" tend to emerge in specific domains, and depending on your stack it may be difficult to implement across the whole codebase (Prettier does not have a C# formatter, for example)
🟡 Can take the team time to adapt to a style they might not have chosen, but this is probably less charged than debating every detail of code style because the decision-makers are far removed from the team
🔴 Can be hard to know which formatter to choose when a clear leader does not exist in the space — and sometimes there isn't a popular option at all
A popular opinionated formatter is Prettier.
Prettier is an aggressive formatter aimed at front-end code that offers the following kinds of customizations, with some direct mappings to Editorconfig if Editorconfig support is flagged and an Editorconfig file exists:
{
"trailingComma": "es5",
"tabWidth": 4,
"semi": false,
"singleQuote": true
}🟢 Popular flavor
🟢 Very good front-end support, including the many JavaScript frameworks
🟢 Light
🟢 Easy to control per project
🔴 No C# support
🔴 No Visual Studio support, but great VS Code support
🔗 Prettier Configuration with Editorconfig
There have been some community efforts to introduce Prettier to the Microsoft stack. A JavaScript-only Visual Studio plug-in does not appear supported anymore. A C# (not-Razor for now) Prettier inspired plug-in is CSharpier.
I don't know much about this suite, but it appears to be a full package and not just a formatter. It is paid. A downside is that your team has to use an IDE that is compatible, and be on Windows. I do not believe you could work this tool/formatting choice into a pipeline.
🟢 Among most downloaded plug-ins for Visual Studio 2022
🟢 Supports whole stack (everything but Razor?) including JavaScript, Typescript, CSS, HTML
🟡 Niche flavor (JetBeans) — not a large community beyond this scope
🔴 Paid product
🔴 Windows and Visual Studio only (plus their own IDE, Rider)
🔴 Possibly a heavy tool?
Testing what this does?