The Brilliant JavaScript Coder's Guidebook (GoodJsCode™)

Write elegant code by following good practices 🚀

I'm Pierre-Henry Soria. An enthusiastic and passionate software engineer. Originally from Brussels (Belgium) 🍫, I'm currently living in the wonderful land called “Australia” (Adelaide) 🦘

I've been coding for over 10 years. Today, I decided to share my knowledge in terms of writing professional, clean and scalable code 🤩

Every day, I review hundreds of lines of code. Brand new micro-services, new features, new refactoring, hotfixes, and so on. I've seen so many different coding styles as well as good and bad coding habits from the developers I've been working with.

With this book, you will get the essentials to know, straight to the solution for writing better and cleaner code. It's a practical book. You won't have superfluous information. Just the important things ✅

Time is so valuable and important (even more as a software engineer), so I will only share what you need to know, without unnecessary details, that are there only for making the book fatter.

---

📖 Table of Contents

• Don’t comment on what it does. Write what it does.
• The “One Thing” principle
• Boat anchor - Unused code
• Minimalist code
• You Aren't Going To Need This... (a.k.a. YAGNI)
• Reuse your code across your different projects by packing them into small NPM libraries
• Tests come first. Never Last
• Import only what you need
• Filtering falsy values from arrays the clean way
• Conditions into clear function names
• Readable Name: Variables
• Readable Name: Functions
• Readable Name: Classes
• Fail Fast principle
• Guard Clauses approach
• .gitignore and .gitattributes to every project
• Demeter Law
• Debugging efficiently
• Fewer arguments is more efficient
• Stub/mock only what you need
• Remove the redundant things
• Ego is your enemy
• Don’t use abbreviations
• American English spelling. The default choice when coding
• Destruct array elements in a readable way
• Readable numbers
• Avoid “else-statement”
• Prioritize async/await over Promises
• No magic numbers
• No magic strings
• Always use assert.strictEqual
• Updating an object - The right way
• Stop using Date() when doing benchmarks
• Lock down your object
• Consider aliases when destructing an object
• Always use the strict type comparison
• Avoid using export default as much as you can
• Always write pure functions
• Don't overcomplicate things
• Linters and Formatters
• About the author

Don’t comment on what it does ❌ Write what it does ✅

Self-descriptive code is very important. Your code should simply self-document itself.

It's crucial to name your functions and variables in simple and explicit words so that they say what they do (just by reading their names).

If the code requires too many comments to be understood, it means the code needs to be refactored. The code has to be understood by reading it, not by reading the comments. And the same applies when you write tests. Having to justify what the code does is usually a bad sign of a code smell.

Your code has to be your comments. At the end of the day, as a developer, we tend to be lazy and we don't read the comments (carefully). However, the code, we always do.

Icing on the cake, it's always more rewarding and requires less time to write self-descriptive code rather than commenting it.

❌ Bad practice

let validName = false;
// We check if name is valid by checking its length
if (name.length >= 3 && name.length <= 20) {
  validName = true;
  // Now we know that the name is valid
  // …
}

const sr = 8.79; // Saving Rate

✅ Good example

const isValidName = (name) => {
  return (
    name.length >= config.name.minimum && name.length <= config.name.maximum
  );
};
// …

if (isValidName('Peter')) {
  // Valid ✅
}

const savingRate = 8.79;

Remember, your job is to write efficient and meaningful code, not endless comments.

⬆️ Back to top

---

<!-- New Section (page) --> <!-- (c) Pierre-Henry Soria -->

The “One Thing” principle 1️⃣

When writing a function, remind yourself that it should (ideally) do only one (simple) thing. Think about what you have already learned concerning comments. The code should say everything. No comments should be needed. Splitting the code into small, readable functions and reusable portions of code will drastically improve your code's readability and eliminate the need to copy/paste the same piece of code just because it hasn't been properly moved into reusable functions or classes.

Just as individual LEGO blocks can be combined to create larger structures, your functions should be small, focused units that can be composed together to accomplish more complex tasks.

❌ Non-readable function

function retrieveName(user) {
  if (user.name && user.name !=== 'admin' && user.name.length >= 5) {
    return user.name;
  }
  // ...
}

✅ One Thing. Neat & Clean

const isRegularUser = (name) => {
  return name !=== config.ADMIN_USERNAME;
}

const isValidNameLength = (name, minimumLength = 5) => {
  return name.length >= minimumLength;
}

const isEligibleName(name) {
  return isRegularUser(name) && isValidNameLength(name);
}

// …

function retrieveName(user) {
  const name = user?.name;

  if (isEligibleName(name)) {
    return user.name;
  }
}

Uncle Bob explains this concept as "Extract Till You Drop" where you continuously extract your code into smaller and more manageable components.

⬆️ Back to top

---

<!-- New Section (page) --> <!-- (c) Pierre-Henry Soria -->

Boat anchor (AKA Tree Shaking 🌳)

Never keep unused code or commented code, “just in case” for history reasons.

Sadly, it's still very common to find commented code in pull requests.

Nowadays, everybody uses a version control system like git, so there is always a history where you can look and go backward if needed.

❌ Downsides of keeping unused code

1. We think we will come back to removing it when it's time. Very likely, we will get busy with something else and we will forget to remove it.
2. The unused code will add more complexity for a later refactoring.
3. Even if unused, it will still show up when searching in the codebase (which adds more complexity too).
4. For new developers joining the project, they don't know if they can remove it or not.

✅ Action to take

Add a Bitbucket/GitHub pipeline or a git hook on your project level for rejecting any unused, dead, and commented code.

⬆️ Back to top

---

<!-- New Section (page) --> <!-- (c) Pierre-Henry Soria -->

Minimalist code

Measuring programming progress by lines of code is like measuring aircraft building progress by weight.

— Bill Gates

Coding in a minimalist way is the best pattern you can follow! Simplicity over complexity always wins! 🏆

Each time you need to create a new feature or add something to a project, see how you can reduce the amount of code.

There are so many ways to achieve a solution. And there is always a shorter and cleaner version which should always be the chosen one.

Think twice before starting to write your code. Ask yourself "what would be the simplest and most elegant solution I can write", so that the written code can be well-maintained over time and very easily understood by other developers who don't have the context/acceptance criteria in mind.

Brainstorm about it. Later, you will save much more time while writing your code.

⬆️ Back to top

---

<!-- New Section (page) --> <!-- (c) Pierre-Henry Soria -->

You Aren't Gonna Need It (YAGNI)

❌ Don't code things "just in case" you might need it later.

Don't spend time and resources on what you might not need.

✅ You need to solve today's problem today, and tomorrow's problem tomorrow.

⬆️ Back to top

---

<!-- New Section (page) --> <!-- (c) Pierre-Henry Soria -->

Reuse your code across your different projects by packing them into small NPM libraries

❌ Wrong approach

My project is small (well, it always starts small). I don’t want to spend time