Web dev style guide

Published 2 months ago

I maintain a style guide for the way I write code 🤓

I follow my style guide rules extremely strictly in Baleada packages and in my personal projects, where I have free reign to enforce all my weirdest opinions. If you're out there source-diving my open source work, this style guide might explain some of the stuff you see.

This is a living document—it needs more work, and I tend to tweak rules, so I'll be back to edit in the future.

TypeScript rules

Variable naming

For the purposes of this section, Noun can be an actual noun, or an adjective that functions as a noun.

Variables named <verb>:

Variables named to<Noun>:

Variables named narrow<Noun>:

Variables named predicate<Noun>:

Variables named create<FunctionName>:

Variables named preciselyCreate<FunctionName>:

Variables named create<Noun>:

Variables named preciselyCreate<Noun>:

Variables named create<Noun>Effects:

Variables named create<Noun>Transforms:

Variables named create<Noun>Fns:

Variables named get<Noun>:

Variables named use<Noun>:

Variables named <eventType>Effect:

Variables named <noun>By<OtherNoun>:

Variables named narrowed<Noun>:

Variables named is<Noun>:

Mutability

Immutability contributes to predictable systems. Prefer immutability.

When it's necessary and/or more readable to declare a variable with let and mutate it from inside if or switch statements, or for or while loops, prefer extracting that code to a separate function or IIFE that returns the let variable.

The major exception to this rule of course is reactive state, which is designed to be mutated, and comes with tools to help track and debug mutations, keeping the system predictable.

Conditionals

When handling booleans, prefer if statements, ternaries, and logical operators over switch statements.

Prefer switch statements for anything that is not a boolean.

Nested ternaries are fine if they're well formatted, but if statements with early returns are good for reduced indentation.

Avoid else. Prefer if statements with early returns.

if statements should always early return.

Function parameters

I need to make a decision tree for parameter design.

Factors to consider:

Pipelines

Prefer pipelines over method chaining, to maximize chances of tree-shaking.

If the piped value is an array at every stage of the pipeline, use the lazy-collections pipe function and iterator helpers.

Otherwise, use the Pipeable class from @baleada/logic.

Function organization

Functions should very roughly follow this distribution:

• Nearly all functions should have fewer than 50 lines of logic
• Roughly 30% of functions should have fewer than 10 lines of logic
• When any block of tightly coupled UI logic exceeds 7 lines, it should almost always be extracted into a one-off, non-reusable function

When defining a tree of functions, write it in depth-first order. In other words,

• Write the top-level function first
• If the top-level function calls a nested function or references a nested constant ("child"), define that nested function or constant next
• If the nested function calls another nested function ("grandchild"), define that next
• Once all grandchildren are defined, define the next child function
• Once all children are defined, define the next top-level function

Since JS constants execute immediately and don't allow you to reference a constant before it's defined, this style must be changed for nested constants. Nested constants should be defined in reverse-depth-first order. In other words, write the grandchildren constants first, then the children constants, then the top-level constants.

Type organization

When defining a tree of types, write it in depth-first order. In other words,

• Write the top-level type first
• If the top-level type calls a nested type or references a nested constant ("child"), define that nested type or constant next
• If the nested type calls another nested type ("grandchild"), define that next
• Once all grandchildren are defined, define the next child type
• Once all children are defined, define the next top-level type

Vue rules

All TypeScript rules also apply to Vue code.

Component categories

All components fit into the following categories, sorted here from least to most complex markup structure:

Component names should start with their category:

Component code organization

Code should very roughly follow this distribution:

• Nearly all components should have fewer than 50 lines of UI logic, i.e. code in script setup
• Roughly 30% of components should have fewer than 10 lines of UI logic
• Nearly all components should have fewer than 100 lines of template code
• Roughly 30% of components should have fewer than 30 lines of template code
• When any block of tightly coupled UI logic exceeds 7 lines, it should almost always be extracted into a one-off, non-reusable composable
• When any block of tightly coupled template code exceeds 50 lines, it should almost always be extracted into a one-off, non-reusable component

React rules

All TypeScript rules also apply to React code.

Component code organization

Code should very roughly follow this distribution:

• Nearly all components should have fewer than 50 lines of UI logic, i.e. code before returning JSX
• Roughly 30% of components should have fewer than 10 lines of UI logic
• Nearly all components should have fewer than 100 lines of JSX
• Roughly 30% of components should have fewer than 30 lines of JSX
• When any block of tightly coupled UI logic exceeds 7 lines, it should almost always be extracted into a one-off, non-reusable hook
• When any block of tightly coupled JSX exceeds 50 lines, it should almost always be extracted into a one-off, non-reusable component

CSS rules

Tailwind class order:

Prefer adding gap to a parent element rather than margin to a child element. Whitespace is a concern of parent elements, not their children.