JavaScript/TypeScript (JS/TS) is a multi-paradigm language which gives the users full freedom over how to write their code.
This is a very double-edged sword within teams.
That is why we have written this handbook to standardise our practices and provide a place for members to look up what to do if they are confused.
How to read this guide
If you just want to learn our rules/guidelines and don't care for the explanations, take a quick look at the outline/headers.
In the headers we try to summarise the points into quick imperative commands,
then articulate why in the body of the section.
Optionally, a category name is added to clearly categorise what topic we are talking about.
TODO: make this section better, add examples of good times to optimise f. eks.
While performance is important, most optimisations are brilliantly automated by engineers far better than ourselves.
Trying to optimise our code most often reduces readability both for our team members,
and for the compiler tasked with optimising our code.
Mind you, this doesn't mean write shit code.
What it means is don't try to be cute,
Keep It Simple Stupid (KISS).
We try to make our code as modular as possible as it is the most maintainable programming paradigm and most idiomatic for Javascript.
Modular Programming | How to write good procedural code - YouTube, Brian Will
Difference between modular programming and object-oriented programming - StackOverflow
Because it sucks and makes it even harder to maintain a codebase (its hard enough to use Javascript in a team).
If you want to learn more about why OOP sucks I highly recommend this video by Brian Will, which might ironically make you better at writing good OOP code for when you inevitably get a corporate job.
Object-Oriented Programming is Bad - YouTube, Brian Wil
TODO: Write something about how to write good functional good for logic modules
In JS/TS
Logic modules should contain:
- constant values
- types
- pure functions
- function closures (instead of classes) Write closures, not classes
Within a web project, routes and pages should be the only state modules.
Pure functions are functions where the output only differ if its input differ.
This means calling the functions repeatedly with the same arguments should always return the same results.
This lets us rewrite the entire workings of the inner function body,
as long as we make sure the output stays the same.
This drastically improves predictability which also makes the codebase easier to maintain.
Using var for variable declarations is widely accepted as bad practice.
var is bound to function scope while let and const are bound to block scope.
This leads to confusing and unintuitive behavior.
TODO: Give some examples
Use whichever syntax makes the code more readable.
Only exception is if it affects performance like processing multiple asynchronous operations in parallel instead of sequentially.
Whats more important than having a steadfast rule to stand by is to understand how async await and promise work.
What operations are essentially equivalent and what operations execute differently.
Async await vs promises - StackOverflow
Why not write classes?
Writing function closures instead of classes is more representative of what happens under the hood.
Function closures also has the benefit of avoiding the extremely confusing this keyword in JS/TS and instead just reference variables directly.
Closures vs classes - StackOverflow
Essential Typescript for React - Blogpost, Jacob Paris
We are not writing a book.
We are writing a guide one should be able to skim through and get the gist of it.