On code formatters, code readability, and maintainability
Code is written by humans, to be read by humans. It has to be formatted functionally, but also in a way that is readable and enjoyable. If readability wasn’t important, we would not spend so much time arguing about the beauty of some languages in terms of their syntax, the best way to format code, and language maintainers would not spend so much time studying how to make the language syntax more legible.
Readability does not attest the reliability of the code. It makes reading and modifying such code easier for developers. Unfortunately, great readability is not easy to achieve. Part of it depends on the language itself, while the rest depends on how readable the subject finds the language and the formatting style used. Readability is subjective. There are aspects of it that can be considered objective, things that can be proven to work better for most eyes, formats that can be demonstrated to be less tiring for the brain. However, all these things put together have a different impact on how we perceive readability and that makes it subjective.
Code formatters have a naive goal to make code more readable by applying automatically, agreed-upon, rules to code files. Consistency, along with time to focus on more important things, are two (perhaps the most common) selling points of code-formatters. Readability makes these tools controversial and hard to accept for some people. Leasving aside the familiarity heuristic/bias we all have, some of the decisions coded in these formatters will never work well for some people.
Because of this, maintainers of these tools have an extra weight on their shoulders and many more decisions to make. While most of the tools are based upon coding-styles decided by the language community, they all face the same fundamental decision of what level of configuration should be made available to consumers of the tool.
Make the tool too configurable and people will likely derail from the coding guidelines agreed by the community. Make the tool too strict and people will be frustrated by things they would like to change but are now forced to use. The latter favors consistency but penilizes readability for some people.
On the consumers side, having an extremely configurable tool brings back all the discussions the tool wanted to avoid in the first place. One would hope these would be a one-off discussions but the reality is that there will always be someone that is not fully on-board with some of the guidelines, which means the topic of readability will often be brought back on the table. On the other side, having a non-configurable tool may go as far as pushing away contributors. As extreme as this may sound, some people find non-readable code unbearable and hard to work with.
Deciding what guidelines to make configurable (or, as a consumer, what configuration to customize) can be tiring as the difference of opinions are often big. The sooner in the life of a project these decisions are made, the easier it will be to make them. Approaching these discussions with as much objectivity as possible will make it easier to come up with a decision that will be easier to prove and support even if it is not perfect for everyone. In a more practical example, prefer mainteinability over just making the code “prettier”, prefer the option that will reduce the merge conflicts, etc. In other words, pick the option that can be technically proven to help the maintenance of the project. This won’t make the code readable for everyone but it will reduce the subjectivity of the choices being made.
As usual, none of what is written here can be used as a silver bullet. Thoughts and considerations are required just like in everything else. What is important is that code must be readable by humans, and processed by machines Projects will be hard to maintain, and they will likely die, if one of these attributes is missing.