List of rules and conventions I follow when writing code

[thetutlage]

In this post, I share the coding style, naming conventions, and the file structure naming conventions I will be using. Let's group all these under the Effective TypeScript name (borrowed from Effective Dart).

This post is not a guideline for others to follow. It is just a collection of principles and rules I have set for myself.
However, you are free to follow them if they click with your coding style.

The following sources inspire the rules I have set for myself.

• Effective Dart
• https://google.github.io/styleguide/tsguide.html

Naming conventions

This is not an extensive list of all the naming conventions I follow. Instead, it is a collection of the trickiest ones, which took some time to figure out.

Feel free to leave comments on the ones you want to discuss. I will try my best to answer :)

Avoid abbreviations

Avoid abbreviations and use complete words. Unless, the abbreviation is a standardised term. For example:

• It is fine to use IO, Id, DB, HTTP.
• Whereas, one must not use req -> request, res -> response, e -> error, or btn -> button.

Here's a great conversation on the same.

Use a non-imperative verb phrase for a boolean property

Non-imperative words are anything that is not a command. So for boolean properties, it is recommended to use non-imperative verb phrases.

// ❌ Do not use
if (errors.empty)

// ✅ Recommended
if (errors.isEmpty)

// ❌ Do not use
if (account.closed)

// ✅ Recommended
if (account.isClosed)

Dart language design guide has a few more excellent examples of the same.

Use language (JavaScript) conventions

The readable/good naming conventions can often go against the grain of the language itself.

For example, it is more readable to write users.where((age) => age > 18). However, the JavaScript users are already familiar with the filter method and its expected output.

Therefore, it is recommended not to invent helpers who have the same utility as the functions already available in the language.

I was in favor of beautifying the language for a long time. But, I realized that doing so also needs continuous evangelism and learning resources to educate everyone. If you cannot do that, it's better to stick to something others already know.

Another example is the get and the set prefixes. Many languages guide against using them as a prefix on method names.

However, JavaScript native APIs uses these prefixes quite a lot. For example: new Date().getDate(), new Date().setHours() and therefore you can follow the language conventions in your APIs as well.

File structure naming conventions

I used all lowercase names for the root level directories and PascalCase names for sub-directories for a long time. The file name was based upon the contents of the file.

• A file that exports the class was named PascalCase.
• A file that exports functions was named snake_case, or dash-case.

There is no consensus on how files should be named in JavaScript. Each sub-community has its own rules or no rules altogether.

Also, PascalCase naming can have issues when the file system on your development machine is not case-sensitive. Therefore, an import statement might work fine on your computer but will fail on the server (if the server has a case-sensitive file system).

After following the Dart guide, Google JavaScript guide, and looking at some of the angular core codebases, I have decided always to use snake_case for the entire file structure.

• All folders will be named as snake_case.
• All files (regardless of what they export) will be named snake_case.

Class properties vs. getters vs. methods

This is something I have struggled with for a long time. When to use class properties, getters, and methods. I think I have a good mental model around them now.

Never use getters and setters

Getters and setters never convey the operation's intent; they run behind the scenes. Also, I see little to no benefit in using them over a method. Whereas a method also allows me to accept the arguments in the future (possibility to evolve the API without breaking changes).

Use properties when they are defined at the time of instantiating a class

I use class properties only when they are defined at the time of instantiating the class. For example:

class Session {
  id = uuid.v4()
  constructor(public readonly = false) {}
}

You can access the session id and the readonly property directly from the session class instance.

const session = new Session() 
session.id
session.readonly

However, the session data is only available as a method because it is not computed when creating the class instance.

class Session {
  #data = null
  #initiated = false
  
  initiate() {
    this.#initiated = true
    this.data = loadDataFromSomewhere()
  }
  
  all() {
    if (!this.#initiated) {
      this.initiate()
    }

    return this.data
  }
}

As you can notice, the #data property is populated lazily. Therefore, I hide it behind a method call (which also allows populating the property if not done already).

This can be a subjective choice. But, to silence my inner battle, I follow a simple rule. Anything lazily evaluated cannot be accessed as a property and must require a method call.

And do not confuse it something this is initially set to null, but can be mutated afterward. For example, The connection property on some database model.

class BaseModel {
  connection = null
}

Instead of exposing methods like setConnection and getConnection, you can allow mutating the connection property directly. Because the value is this property is never computed and is always defined manually.

const model = new BaseModel()
model.connection = 'mysql'

If the model has a chain-able API, I might introduce the useConnection method to allow fluently setting a connection.

model.useConnection('mysql').someOperation()

EsLint rules

The ESLint rules I follow to keep my codebase consistent.

@typescript-eslint/semi

Use two spaces for indentation. Rule documentation →

{
  "@typescript-eslint/semi": [2, "never"]
}

@typescript-eslint/quotes

Enforce consistent use of either backtick, double, or single quotes. Preference is given to single quotes. Rule documentation →

{
  "@typescript-eslint/quotes": ["error", "single"]
}

@typescript-eslint/space-before-function-paren

Enforce a single consistent space before the function parenthesis. Rule documentation →

{
  "@typescript-eslint/space-before-function-paren": ["error", "always"]
}

@typescript-eslint/indent

Enforce consistent indentation throughout the code. This rule is partly broken for TypeScript. The rule's authors acknowledge this since it is tough to get it right for all different situations.

I have used this rule for years now and didn't have any issues. So please ignore this rule if you are fighting its edge cases. Rule documentation →

{
  "@typescript-eslint/indent": ["error", 2, {
      "SwitchCase": 1,
      "flatTernaryExpressions": false,
      "ignoredNodes": ["TSTypeParameterInstantiation"]
  }],
}

no-irregular-whitespace

Disallow irregular whitespaces. A mix of tabs and spaces will make this rule complain. Rule documentation →

{
  "no-irregular-whitespace": ["error"]
}

no-multiple-empty-lines

Enforces a maximum of one empty line between two code blocks. Rule documentation →

{
  "no-multiple-empty-lines": ["error", { "max": 1 }]
}

one-var

Enforce each variable to be defined in its separate line. Rule documentation →

{
  "one-var": ["error", "never"]
}

no-cond-assign

Disallow defining variables inside conditional blocks. Except for while blocks. Rule documentation →

{
  "no-cond-assign": ["error", "except-parens"]
}

comma-dangle

Force multiline objects, arrays, imports, and exports to have trailing commas. There is a great article on the same, explaining why having trailing commas are helpful.

Rule documentation →

{
  "comma-dangle": ["error", "always-multiline"]
}

eqeqeq

Enforces to use of type-safe equality operators. Rule documentation →

{
  "eqeqeq": ["error", "always"]
}

eol-last

Enforces a new empty line at the end of the file. Rule documentation →

{
  "eol-last": ["error", "always"]
}

new-parens

Enforces construct class instances using the new keyword. Rule documentation →

{
  "new-parens": ["error", "always"]
}

no-caller

Disallows using arguments.caller and arguments.callee properties. Rule documentation →

{
  "no-caller": ["error"]
}

no-constant-condition

Disallows constant expressions inside conditionals. Rule documentation →

{
  "no-constant-condition": ["error"]
}

no-control-regex

Disallows control characters in regular expressions. Rule documentation →

{
  "no-control-regex": ["error"]
}

no-debugger

Disallows the use of the debugger keyword. Rule documentation →

You might find yourself using this rule quite often during development. Therefore, we recommend ignoring the error inside your editor and not turning off the rule.

{
  "no-debugger": ["error"]
}

no-duplicate-case

Disallows duplicate case blocks inside a switch statement. Each case block should handle a unique value. Rule documentation →

{
  "no-duplicate-case": ["error"]
}

no-eval

Disallow usage of the eval method. Rule documentation →

{
  "no-eval": ["error"]
}

no-ex-assign

Disallows re-assigning value to the error object inside the `try/catch block. Rule documentation →

{
  "no-ex-assign": ["error"]
}

no-extra-boolean-cast

Disallows unnecessary value casting to a boolean. Rule documentation →

{
  "no-extra-boolean-cast": ["error"]
}

no-fallthrough

Disallows case statement to fall through. Each case statement should either break or return from its block. Rule documentation →

{
  "no-fallthrough": ["error"]
}

no-inner-declarations

Disallows inner declarations of functions and variables. They should be defined at the top level or inside the top level of a given block. Rule documentation →

{
  "no-inner-declarations": ["error"]
}

no-invalid-regexp

Disallows invalid regular expression strings in RegExp constructors. Rule documentation →

{
  "no-invalid-regexp": ["error", { "allowConstructorFlags": ["u", "y"] }]
}

no-proto

Disallows use of __proto__ property. It has been deprecated. Rule documentation →

{
  "no-proto": ["error"]
}

@typescript-eslint/no-shadow

Disallows re-declaring variables already declared in the outer scope. The rule makes it harder to name things but ensures that wrong variable are not used during refactoring. For example:

The rule will fail because the error variable of the readFile method and writeFile methods can conflict.

// ❌ Incorrect

readFile(filePath, (error, contents) => {
  writeFile(filePath, contents, (error) => {
    if (error) {
    }
  })
})

If we remove the error property from the writeFile callback, our code will still be valid. However, now it is referencing the outer scope
variable.

readFile(filePath, (error, contents) => {
  writeFile(filePath, contents, () => {
    if (error) {
      // code is still valid, but meaning has changed
    }
  })
})

Therefore, this rule is essential to avoid these subtle inconsistencies in the code.

// ✅ Correct
readFile(filePath, (readError, contents) => {
  writeFile(filePath, contents, (writeError) => {
    if (writeError) {
    }
  })
})

Rule documentation →

{
  "@typescript-eslint/no-shadow": "error"
}

no-regex-spaces

Disallows multiple spaces in regular expression literals. Rule documentation →

{
  "no-regex-spaces": ["error"]
}

no-self-compare

Disallows comparisons where both sides are the same. Rule documentation →

{
  "no-self-compare": ["error"]
}

no-sparse-arrays

Disallow arrays with empty slots. Ideally, no one does it on purpose. Rule documentation →

{
  "no-sparse-arrays": ["error"]
}

no-mixed-spaces-and-tabs

Disallows mixed spaces and tabs for indentation. Rule documentation →

{
  "no-mixed-spaces-and-tabs": ["error"]
}

no-unsafe-negation

Disallow unsafe negated expressions.

// ❌ Incorrect

if (!key in object) {
}

// ✅ Correct

if (!(key in object)) {
}

Rule documentation →

{
  "no-unsafe-negation": ["error"]
}

no-new-wrappers

There is a good history behind string, number, and boolean primitives. This rule disallows creating these primitives instances using new String, new Boolean, etc. Rule documentation →

{
  "no-new-wrappers": ["error"]
}

no-self-assign

Disallows assignments where both sides are the same. Rule documentation →

{
  "no-self-assign": ["error"]
}

no-this-before-super

Disallows the use of this before calling super() in constructors. Rule documentation →

{
  "no-this-before-super": ["error"]
}

no-with

Disallows with statements. No one anyways uses it. Rule documentation →

{
  "no-with": ["error"]
}

rest-spread-spacing

Disallow space between rest/spread operators and their expressions. Rule documentation →

{
  "rest-spread-spacing": ["error", "never"]
}

no-trailing-spaces

Disallows trailing whitespace at the end of lines (except comments).Rule documentation →

{
  "no-trailing-spaces": ["error", { "ignoreComments": true }]
}

no-undef-init

Disallows initializing variables to `undefined. Rule documentation →

{
  "no-undef-init": ["error"]
}

no-unsafe-finally

Disallows control flow statements inside finally blocks. This is a great one, do read the ESLint documentation. Rule documentation →

{
  "no-unsafe-finally": ["error"]
}

padded-blocks

Disallows padding within blocks. Rule documentation →

{
  "padded-blocks": ["error", "never"]
}

space-in-parens

Disallows spaces inside of parentheses. Rule documentation →

{
  "space-in-parens": ["error", "never"]
}

use-isnan

Requires calls to isNaN() when checking for NaN. Rule documentation →

{
  "use-isnan": ["error"]
}

valid-typeof

Enforces using a valid data type string when using the typeOf expression. Rule documentation →

{
  "valid-typeof": ["error", { "requireStringLiterals": true }]
}

brace-style

Enforces consistent brace style for blocks, i.e., one true brace style. Rule documentation →

{
  "brace-style": ["error", "1tbs"]
}

curly

Enforces curly braces always to be present. Rule documentation →

{
  "curly": ["error", "all"]
}

@typescript-eslint/naming-convention

• Enforces the variables in camelCase, UPPER_CASE, or PascalCase.
• Types, and Enum to be in PascalCase.
• Class names to be in PascalCase.
  Interfaces should be in PascalCase and should not be prefixed to be I.

Rule documentation →

{
  "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "variable",
        "format": ["camelCase", "UPPER_CASE", "PascalCase"]
      },
      {
        "selector": "typeLike",
        "format": ["PascalCase"]
      },
      {
        "selector": "class",
        "format": ["PascalCase"]
      },
      {
        "selector": "interface",
        "format": ["PascalCase"],
        "custom": {
          "regex": "^I[A-Z]",
          "match": false
        }
      }
    ]
}

handle-callback-err

Enforces to handle the callback error. Rule documentation →

{
  "handle-callback-err": ["error", "^(err|error)$"]
}

max-len

Enforces the code lines to max 100 characters long and comments to be 120 characters long. Except for template literals and string literals containing URLs. Rule documentation →

{
  "max-len": ["error", {
    "code": 100,
    "comments": 120,
    "ignoreUrls": true,
    "ignoreTemplateLiterals": true
  }]
}

no-array-constructor

Disallows creating array using the Array constructor. However, you can create a sparse array of specified size by giving the array's length. Rule documentation →

{
  "no-array-constructor": ["error"]
}

no-unreachable

Disallows unreachable code after return, throw, continue, and break statements. Rule documentation →

{
  "no-unreachable": ["error"]
}

no-multi-spaces

Disallows multiple consecutive spaces. Rule documentation →

{
  "no-multi-spaces": ["error"]
}

unicorn/prefer-module

Enforces the use of ES modules over CJS. This rule disallows using __filename, __dirname, and many similar global properties. Rule documentation →

{
  "unicorn/prefer-module": "error"
}

unicorn/prefer-node-protocol

Enforces the node: prefix when importing native node modules. Rule documentation →

{
  "unicorn/prefer-node-protocol": "error"
}

unicorn/consistent-destructuring

Enforces the use of already destructured objects and their variables over accessing each property individually. Previous destructuring is easily missed, which leads to an inconsistent code style. Rule documentation →

{
  "unicorn/consistent-destructuring": "error"
}

unicorn/filename-case

Enforces all source files to be in snake case. Rule documentation →

{
  "unicorn/filename-case": [
    "error",
    {
      "case": "snakeCase"
    }
  ]
}

unicorn/no-array-for-each

Enforces to use for of loop over forEach loop. Rule documentation →

{
  "unicorn/no-array-for-each": "error"
}

unicorn/no-await-expression-member

When accessing a member from an await expression, the await expression has to be parenthesized, which is not readable. Rule documentation →

{
  "unicorn/no-await-expression-member": "error"
}

unicorn/no-for-loop

Enforces to use for of loop over traditional for loop. Rule documentation →

{
  "unicorn/no-for-loop": "error"
}

unicorn/no-instanceof-array

Disallows using instanceof Array. One must use Array.isArray. Rule documentation →

{
  "unicorn/no-instanceof-array": "error"
}

unicorn/prefer-number-properties

Enforces using methods like parseInt from the Number constructor and not using the global methods. Rule documentation →

{
  "prefer-number-properties": "error"
}

typescript-eslint/explicit-member-accessibility

Turn off explicit accessibility modifiers on class properties and methods. For a long time, they are on, but as we have got private members in JavaScript classes (with runtime safety), there is little or no value in using the private modifier of TypeScript.

Since, I am not using private, there is also no need to use the public modifier, because everything is public by default. Therefore, the only modifier of use is protected.

The following rule forces you to never prefix methods and properties with the public modifier. The same setting for the private does not exist for now, but there is an open issue for the same.

{
  "overrides": [
    {
      "files": [
        "*.ts",
        "*.tsx"
      ],
      "rules": {
        "@typescript-eslint/explicit-member-accessibility": [
          "error",
          { "accessibility": "no-public" }
        ]
      }
    }
  ]
}

How I used to define private and public properties earlier

class Counter {
  private state = 0

  public increment() {
    this.state++
  }
}

How I will define private and public properties moving forward

class Counter {
  #state = 0

  increment() {
    this.#state++
  }
}

[muco-rolle]

Thanks, @thetutlage very helpful

[brkn]

What's your view on inheritance in general?

In my team we've started using noImplicitOverride in the tsconfig. link

class HttpExceptionHandler {
  public async handle() {}
}
 
class AuthExceptionHandler extends HttpExceptionHandler {
  public override async handle() {}
}

[thetutlage]

The noImplicitOverride is something I will use using myself. I discovered it quite late in my TypeScript journey and in fact forgot about it completely.

What's your view on inheritance in general?

Inheritance is okayish. For base classes where you want to inherit a bunch of functions and properties it is fine. Otherwise I use composition. There are some great articles online for "Composition over Inheritance"

[mattkenefick]

I wish those articles were "Composition and Inheritance" because they can be used well together. Picking sides and going all-in on something is bad practice in all parts of life.