Code Principles

Hi All ❤️

There are a few of these principles that will be universally accepted, but not all of them must be completely adhered to. These are merely guidelines,
but ones that have been formalized over a long period of time.

One more thing: even if you have years of experience with them, knowing them won't make you a better software developer right away.
Like wet clay being molded into its final form, every line of code begins as a first draft.
When we review it with our colleagues/friends, we finally chisel out the flaws. Don't be hard on yourself if your early drafts need work. Instead, abuse the code!

Let's code our wisdom like a melodic poetry ❤️

To keep in mind:

• Use type annotations to explicitly declare the types of variables, function arguments, and return values. This makes it clear to other developers (and to the TypeScript compiler) what the expected types are, and can help prevent type errors.

• Use interfaces to define the shape of complex types, such as objects with multiple properties or arrays with specific elements. This can make your code more self-documenting and easier to understand.

• Use classes and encapsulation to organize your code into logical units and protect the internal state of your objects from being modified by external code.

• Follow the SOLID principles of object-oriented design to create code that is easy to understand, maintain, and extend.

DRY (Don't Repeat Yourself)

KISS (Keep it simple, stupid)

YAGNI (You ain't gonna need it)

---

Variables

Use meaningful variable names

Use pronounceable variable names

Use the same vocabulary for the same type of variable

Use searchable names

Use explanatory variables

Avoid Mental Mapping

Use default arguments instead of short circuiting or conditionals

Use enum to document the intent

---

Functions

Function callers and callees should be close

Function arguments (2 or fewer ideally)

Functions should do one thing

Function names should say what they do

Functions should only be one level of abstraction

Remove duplicate code

Set default objects with Object.assign or destructuring

Don't use flags as function parameters

Avoid Side Effects (part 1)

Avoid Side Effects (part 2)

Don't write to global functions

Favor functional programming over imperative programming

Encapsulate conditionals

Avoid negative conditionals

Avoid conditionals

Avoid type checking

Don't over-optimize

Remove dead code

Use iterators and generators

---

Objects and Data Structures

Use getters and setters

Make objects have private/protected members

Prefer immutability

type vs. interface

---

Classes

Classes should be small

High cohesion and low coupling

Prefer composition over inheritance

Use method chaining

---

SOLID

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

Liskov Substitution Principle (LSP)

Interface Segregation Principle (ISP)

Dependency Inversion Principle (DIP)

---

Testing

Testing is more important than shipping. If you have no tests or an inadequate amount, then every time you ship code you won't be sure that you didn't break anything.
Deciding on what constitutes an adequate amount is up to your team, but having 100% coverage (all statements and branches)
is how you achieve very high confidence and developer peace of mind. This means that in addition to having a great testing framework, you also need to use a good coverage tool.

There's no excuse to not write tests. There are plenty of good JS test frameworks with typings support for TypeScript, so find one that your team prefers. When you find one that works for your team, then aim to always write tests for every new feature/module you introduce. If your preferred method is Test Driven Development (TDD), that is great, but the main point is to just make sure you are reaching your coverage goals before launching any feature, or refactoring an existing one.

The three laws of TDD

1. You are not allowed to write any production code unless it is to make a failing unit test pass.

2. You are not allowed to write any more of a unit test than is sufficient to fail, and; compilation failures are failures.

3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

F.I.R.S.T. rules

Single concept per test

The name of the test should reveal its intention

---

Concurrency

Prefer promises vs callbacks

Async/Await are even cleaner than Promises

---

Error Handling

Thrown errors are a good thing! They mean the runtime has successfully identified when something in your program has gone wrong and it's letting you know by stopping function

execution on the current stack, killing the process (in Node), and notifying you in the console with a stack trace.

Always use Error for throwing or rejecting

Don't ignore caught errors

Don't ignore rejected promises

Migrating from TSLint to ESLint

---

Code Organization

Use consistent capitalization

Organize imports

Use typescript aliases

---

Comments

The use of a comments is an indication of failure to express without them. Code should be the only source of truth.

Don’t comment bad code—rewrite it.

— Brian W. Kernighan and P. J. Plaugher

Prefer self explanatory code instead of comments

Don't leave commented out code in your codebase

Don't have journal comments

Avoid positional markers

TODO comments