When the

When the “better coding style” is the wrong style

Code is always read more than it is written or debugged. It is of the utmost importance that code is optimised for readability. And in this regard, it must be written such that the largest amount of people possible can read and understand it as quickly as possible.

The reason the title of this post is so peculiar is that there exists a set of developers who are convinced they possess the “correct way” of writing code, and believe their style to be superior and objectively correct. I would like to illustrate why this is rarely the case.

It takes a lot of humility and introspection to accept community conventions. Of course, there are different coding styles and guides, and I find it is often a matter of taste than a verifiable truth. Having flexibility in terms of where to place the braces, variable and function naming conventions, and other style choices is sometimes beneficial, but almost always harmful. We all have our own preferred way of writing code, and this will sometimes cause conflict in teams, where different people have conflicting opinions and views on what code should look like.

I will argue that keeping in line with coding styles and standards is important even for your personal projects on which you work alone, as this allows you to get used to the conventions of the particular language or framework. This is important, because often, each community will have different opinions and styles of code. You can see this in Rubocop for Ruby, Black for Python, or go fmt. The best guides will homogenise coding style for an entire language, or even an entire company. And, of course, if there are coding style guides out there, it’s better to follow those instead of creating guides from scratch. It may be difficult to follow these standards at first, as there is a significant learning curve, and you may disagree with the format of the finished code.

The primary objective of coding conventions is to establish a harmonious and legible codebase. These guidelines expedite the onboarding process for new developers and streamline ongoing maintenance efforts. While some of these conventions may appear to be arbitrary at first glance, adhering to them significantly fosters a collaborative environment in software development, ensuring that all team members can effortlessly navigate and contribute to the project.

Many of these coding guides will have straightforward integrations with your favourite code editor. The best approach is to have it format on save, this avoids having to run it manually, and committing potentially non-compliant code to your team’s repository. In a team, you should also set git hooks that complain if your code is not formatted as required.

Some examples of conventions:

  • Black (Python):
    • Black enforces a consistent line length (default is 88 characters), which helps to keep code readable on any screen.
    • It formats code in a way that makes diffs easier to read in version control, which is important for understanding changes over time.
  • Rubocop (Ruby)
    • Rubocop enforces naming conventions, which helps to keep code self-documenting and makes it easier for other developers to understand the purpose of different parts of the code.
    • It checks for redundant code and suggests more concise ways of expressing the same logic, promoting cleaner and more efficient code.
  • go fmt
    • go fmt uses tabs for indentation and spaces for alignment, ensuring a consistent look of the code across various editors and viewers.
    • It standardizes the ordering of imports, which can help developers quickly understand the dependencies of a file.

While those seem like sensible choices, there are thousands of choices any individual developer can make in a codebase. For example, indentation styles, naming conventions, Apache Maven directory layout conventions, Node.js directory layout conventions and much more. Like with most things, everyone has their favourite style.