Skip to main content

Coding conventions

· 5 min read

This is another one of those things that every developer has an opinion of. Can't blame them us really. As much as programming is science, it is also an art. And artists have their own temperaments.

Regardless, unlike artists, developers have to work as a team. That means that they have to follow the team's conventions regardless of their preferences.

Many conventions can now be easily enforced via configurations settings, thanks to the ubiquity of VS Code and, to a lesser extent, Prettier.

This article looks at the easy steps we can take to enforce coding conventions easily for a Next.js project.

The preference settings in VS Code, together with a formatter (such as Prettier), can handle most of the coding conventions that a team wants to establish.

One thing to note about the settings in VS Code is that some are conventions that should established for all team members, some are personal preferences, which should remain personal.

My understanding is that workspace settings (specified by the file .vscode/settings.json) override user settings. (If the setting is not specified at the workspace level, it naturally takes the value from the user level.) Therefore it is important to specify what should be set and what should not be.

Below are contents of settings.json that I set for my projects:

{
  "editor.detectIndentation": true,
  "editor.insertSpaces": false,
  "editor.indentSize": "tabSize",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

These settings achieve the following:

  1. Prefer for VS Code to determine whether to use tabs or spaces based on what is currently being used in the file being edited. ("editor.detectIndentation": true)
  2. If the file is empty (or if VS Code cannot determine the pre-existing indentation convention in the file), tell VS Code to use tabs instead of spaces for indentation. ("editor.insertSpaces": false)
  3. Use the indentation space specified by the tabSize setting whose value should be specified by the programmer at the user level. ("editor.indentSize": "tabSize")
  4. Format the file when it is saved. ("editor.formatOnSave": true)
  5. Use the Prettier formatter to format the file when saving. This is required for the above setting to have any effect. ("editor.defaultFormatter": "esbenp.prettier-vscode")

Other settings such as the tabSize ("editor.tabSize": 2) are not specified here because they are meant to be personal preferences.

note

Now you may be wondering what is the significance of these settings if they are meant to be overridden during saving by Prettier? Fair point.

It is true that Prettier will change the indentation when the files are saved. These settings here help to keep the behaviour consistent so that there are minimum changes between when the programmer is editing the files and after they are saved.

info

My position on using tabs versus spaces for indentation has changed. With tabs, the programmer can choose how the tabs are actually represented. If he/she so chooses, the setting editor.tabSize can be changed to 4 (or 3 if you are crazy!).

For Next.js projects that are scaffolded using npx create-next-app there should be a file .eslintrc.json which contains the contents below:

{
  "extends": "next/core-web-vitals"
}

I leave this untouched as the defaults have worked well for me.

What is most important is the use of the Prettier plugin that performs the task of formatting the files before they are saved. The plugin can be configured using the .prettierrc file in the project.

{
  "useTabs": true,
  "printWidth": 80,
  "singleQuote": true,
  "trailingComma": "es5",
  "semi": true
}

These settings are applied when the files are saved in VS Code:

  1. Use tabs to indent the lines of code. ("useTabs": true)
  2. Wrap the line if there are more than 80 characters in the line. ("printWidth": 80)
  3. Use single quotes where possible. ("singleQuote": true)
  4. Apply a trailing comma in the style ECMAScript 5, which means commas are added to the last line in a multi-line JSON definition. ("trailingComma": "es5")
  5. Always place a semicolon at the end of a statement. (I'm old school that way) ("semi": true)

These configurations might seem trivial but they go a long way in ensuring that code review is not unnecessary hampered by redundant changes such as tabs being replaced with spaces. Take a look below:

example of a diff of spaces and tabs

This diff essentially has no differences between the changes except that one is indented by spaces (new) and one is indented by tabs (old).

Now imagine this expanded to multiple files.

This is no exaggeration. I was a consultant to a project team for a while. They had hired a remote developer who was maintaining a legacy Java codebase.

No one ever reviews the code made by the remote developer not because no one in the team could do it but because every commit involved thousands of lines of code across multiple files. This happened because there wasn't a lead who enforced coding conventions for the team. The thousands of lines of changes were mostly a change in the indentation characters. 🤦 As a result, no one in the team knew what changes the remote developer had made.

This experience further consolidated my view that coding conventions are not a nice-to-have but a must-have for a team.

One last thing to note, the changes made by Prettier as specified in .pretterrc are enforced when the programmer saves the file in VS Code itself that has the Prettier formatter. I thought this was obvious, but sometimes the obvious bears repeating.