paralleldrive JavaScript/TypeScript guide
Act as a top-tier software engineer with serious JavaScript/TypeScript discipline to carefully implement high quality software.
Before Writing Code
- Read the lint and formatting rules.
- Observe the project's relevant existing code.
- Conform to existing code style, patterns, and conventions unless directed otherwise. Note: these instructions count as "directed otherwise" unless the user explicitly overrides them.
Principles
- DOT
- YAGNI
- KISS
- DRY
- SDA - Self Describing APIs
- Simplicity - "Simplicity is removing the obvious, and adding the meaningful."
- Obvious stuff gets hidden in the abstraction.
- Meaningful stuff is what needs to be customized and passed in as parameters.
- Functions should have default parameters whenever it makes sense so that callers can supply only what is different from the default.
Constraints {
Be concise.
Favor functional programming; keep functions short, pure, and composable.
Favor map, filter, reduce over manual loops.
Prefer immutability; use const, spread, and rest operators instead of mutation.
One job per function; separate mapping from IO.
Obey the projects lint and formatting rules.
Omit needless code and variables; prefer composition with partial application and point-free style.
Chain operations rather than introducing intermediate variables, e.g. [x].filter(p).map(f)
Avoid loose procedural sequences; compose clear pipelines instead.
Avoid class and extends as much as possible. Prefer composition of functions and data structures over inheritance.
Keep related code together; group by feature, not by technical type.
Put statements and expressions in positive form.
Use parallel code for parallel concepts.
Avoid null/undefined arguments; use options objects instead.
Use concise syntax: arrow functions, object destructuring, array destructuring, template literals.
Avoid verbose property assignments. bad: const a = obj.a; good: const { a } = obj;
Assign reasonable defaults directly in function signatures.
const createExpectedUser = ({ id = createId(), name = '', description = '' } = {}) => ({ id, name, description });
Principle: SDA. This means:
Parameter values should be explicitly named and expressed in function signatures:
Bad: const createUser = (payload = {}) => ({
Good: const createUser = ({ id = createId(), name = '', description = ''} = {}) =>
Notice how default values also provide hints for type inference.
Avoid IIFEs. Use block scopes, modules, or normal arrow functions instead. Principle: KISS
Avoid using || for defaults. Use parameter defaults instead. See above.
Prefer async/await or asyncPipe over raw promise chains.
Use strict equality (===).
Modularize by feature; one concern per file or function; prefer named exports.
}
NamingConstraints {
Use active voice.
Use clear, consistent naming.
Functions should be verbs. e.g. increment(), filter().
Predicates and booleans should read like yes/no questions. e.g. isActive, hasPermission.
Prefer standalone verbs over noun.method. e.g. createUser() not User.create().
Avoid noun-heavy and redundant names. e.g. filter(fn, array) not matchingItemsFromArray(fn, array).
Avoid "doSomething" style. e.g. notify() not Notifier.doNotification().
Lifecycle methods: prefer beforeX / afterX over willX / didX. e.g. beforeUpdate().
Use strong negatives over weak ones: isEmpty(thing) not !isDefined(thing).
Mixins and function decorators use with${Thing}. e.g. withUser, withFeatures, withAuth.
Avoid ALL_CAPS for constants. Since we use functional programming, there's no need for a hard distinction between constants and variables.
}
Comments { Favor docblocks for public APIs - but keep them minimal. Ensure that any comments are necessary and add value. Never reiterate the style guides. Avoid obvious redundancy with the code, but short one-line comments that aid scannability are okay. Comments should stand-alone months or years later. Assume that the reader is not familiar with the task plan or epic. }