Code Style: Things that aren't being caught by eslint

[personalizedrefriger]

Note: I might be wrong about some of the rules below. If so, please correct me!

Summary

Code feedback has included suggestions not caught by eslint. The goal of this document is to collect a list of common stylistic issues that are not auto-detected/fixed by eslint.

Rules

Use TypeScript for new files

Creating a new .ts file

Because the TypeScript compiler generates .js files, be sure to add these new .js files to .eslintignore and .gitignore.

To do this,

1. If the TypeScript compiler has already generated a .js file for the new .ts file, delete it.
2. Run yarn run updateIgnored in the root directory of the project (or yarn run postinstall)

---

Filenames

• camelCase.ts: Files that export multiple things.
  • Example: checkForUpdates.ts
• PascalCase.ts: Only if the file contains a single class, which is the default export.
• types.ts or fooTypes.ts: Shared type definitions
  • Example : types.ts

---

Use camelCase for constants in new code

Bad:

// Bad! Don't use in new code!
const GRAVITY_ACCEL = 9.8;

Good:

const gravityAccel = 9.8;

---

Indent using tabs

VSCode: In vscode, be sure to check whether new files are created with tab or space indentation! Spaces can be converted to tabs using the command palette.

---

Avoid ==

Use === to check equality. This keeps our code style consistent across TypeScript and JavaScript files and avoids a misleading compiler error message.

See also

• Unofficial TypeScript style guide, == vs ===
• More about == vs === in TypeScript.

---

Declare variables just before their usage

What about numeric constants? E.g.

const gravityAcceleration = 9.8; // m/s

BAD:

// Bad!
let foo, bar;

const doThings = () => {
	// do things unrelated to foo, bar
};

// Do things involving foo and bar
foo = Math.random();
bar = foo + Math.random() / 100;
foo += Math.sin(bar + Math.tan(foo));
...

Good:

...
const doThings = () => {
	// do things unrelated to foo, bar
};

// Do things involving foo and bar
let foo = Math.random();
let bar = foo + Math.random() / 100;
foo += Math.sin(bar + Math.tan(foo));
...

---

Prefer const to let (where possible)

---

Prefer () => {} to function() { ... }

Prefer arrow functions to function() { ... } in new code.

// Bad!
function foo() {
	...
}

Good:

const foo = () => {
	...
};

---

---

React

Use react custom hooks to simplify long code

If eslint gives an error about useFoo being called outside of a component, be sure the custom hook is titled appropriately.

---

See also

Other projects' style guides

We aren't using these guides, but they may still be helpful!

• TypeScript Deep Dive — Style Guide
• Google TypeScript style guide
  • See also ts.dev's style guide, which is based on the Google style guide.
• Javascript standardstyle
  • Possibly useful for adding to .eslintrc.js: lists eslint configuration flags for each of their suggestions

Posts/resources related to Joplin's style

• Post: Troubleshooting FAQ and collecting topic for contributing to Joplin codebase
• Post: How to style your code
• GSoC: https://joplinapp.org/gsoc2022/pull_request_guidelines/
• GitHub: .eslintrc.js

[laurent]

I've already tried adding these rules to eslint but the difficulty is the existing code - there's too much to update (for example for strict equality or camelCase), which in some cases could cause subtle regressions.

Ideally we'd setup the rules so that they only apply to new code, but I'm not sure it's possible to do that.

[laurent]

Your document is very good though, any chance you could add this to a file in "readme/coding_style.md" and link to it from CONTRIBUTIING.md (from the coding style section)?

[personalizedrefriger]

I can do that!