
## Table of Contents

1. [Introduction](#introduction)
2. [Why Cancellation Matters in Web APIs](#why-cancellation-matters-in-web-apis)
3. [How CancellationToken Works in ASP.NET Core](#how-cancellationtoken-works-in-aspnet-core)
4. [Best Practices by Layer](#best-practices-by-layer)
5. [Demo: Detecting Cancellation in Practice](#demo-detecting-cancellation-in-practice)
6. [Testing Cancellation: Client Scenarios](#testing-cancellation-client-scenarios)
7. [Summary Checklist](#summary-checklist)
8. [References](#references)

---

## Introduction

Handling request cancellation is essential for building robust, scalable ASP.NET Core Web APIs. This post covers the best practices for using `CancellationToken`—from API to service and data layers—so your app can respond quickly to client disconnects and avoid wasted work.

## Why Cancellation Matters in Web APIs

When a client disconnects (closes a browser tab, navigates away, or cancels a request), the server should stop any unnecessary work. ASP.NET Core provides a `CancellationToken` for every request, allowing you to:

- Free up resources immediately
- Avoid running expensive or irreversible operations
- Improve scalability and responsiveness

## How CancellationToken Works in ASP.NET Core

- ASP.NET Core injects a `CancellationToken` into every controller action.
- The token is triggered if the client disconnects or cancels the request.
- Many async APIs (like `Task.Delay`, `HttpClient`, EF Core) already respect the token.

## Best Practices by Layer

**Based on expert guidance:**

- **API Layer:**
  - Never check the token manually. ASP.NET injects and manages it for you.
  - Only catch `OperationCanceledException` at the top level if you want to log or return a custom status code.
- **Service Layer:**
  - Add manual checks only:
    - Before starting slow or critical work (in case the client already disconnected)
    - Between long-running steps or before irreversible actions (e.g., sending an email)
  - Use `cancellationToken.ThrowIfCancellationRequested();` where appropriate.
  - Never check manually. Most async APIs (EF Core, `Task.Delay`, `HttpClient`) already handle the token.

**Mental test:**
> "Am I doing slow work that the framework can't see?" If yes, add a check. If not, just pass the token.

## Demo: Detecting Cancellation in Practice
## IsCancellationRequested vs ThrowIfCancellationRequested

When should you use `cancellationToken.IsCancellationRequested` instead of `ThrowIfCancellationRequested()`?

- Use **IsCancellationRequested** when you want to check for cancellation and exit gracefully—without throwing an exception. This is ideal for loops, background services, or cleanup code where you can simply return or break.
- Use **ThrowIfCancellationRequested()** when you want to immediately abort execution and bubble up an `OperationCanceledException`. This is best for service/business logic where you want to stop work and let higher layers handle the cancellation (logging, status code, etc.).

**Summary:**
- Use `IsCancellationRequested` for silent, graceful exits.
- Use `ThrowIfCancellationRequested()` to enforce immediate cancellation and propagate the exception.

**Example:**

```csharp
// Graceful exit in a loop
while (!cancellationToken.IsCancellationRequested)
{
  await DoWorkAsync();
}
// Immediate abort in business logic
cancellationToken.ThrowIfCancellationRequested();
DoCriticalWork();
```

### Backend API Example

```csharp
[HttpGet("slow-report")]
public async Task<IActionResult> GetSlowReport(CancellationToken cancellationToken)
{
    _logger.LogInformation(">>> Request started");
    cancellationToken.ThrowIfCancellationRequested();
    try
    {
        // Step 1 — simulate slow DB query
        _logger.LogInformation(">>> Starting DB query...");
        await Task.Delay(5_000, cancellationToken);
        _logger.LogInformation(">>> DB query done");

        // Step 2 — simulate heavy CPU work
        _logger.LogInformation(">>> Building report...");
        await Task.Delay(5_000, cancellationToken);
        _logger.LogInformation(">>> Report built");

        return Ok(new { message = "Done" });
    }
    catch (OperationCanceledException)
    {
        _logger.LogWarning(">>> REQUEST CANCELLED — client disconnected");
        return StatusCode(499);
    }
}
```

- If the client cancels after 2 seconds, logs show:
  - `>>> Request started`
  - `>>> Starting DB query...`
  - `>>> REQUEST CANCELLED — client disconnected` (never reaches "DB query done")

## Testing Cancellation: Client Scenarios

### 1. Manual Cancellation with HttpClient

```csharp
using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(2));
using var http = new HttpClient();
try
{
    var response = await http.GetAsync("https://localhost:7001/api/slow-report", cts.Token);
    Console.WriteLine($"Completed: {response.StatusCode}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Cancelled — simulates client disconnect");
}
```

- This approach is repeatable and precise for testing.

### 2. Browser Tab Close / Navigation

```javascript
fetch('https://localhost:7001/api/slow-report')
  .then(r => r.json())
  .then(console.log);
// Now close the tab — ASP.NET Core detects the TCP connection drop and fires the CancellationToken
```

### 3. UI Demo (Sample Client)

The included demo client lets you:
- Start a long-running request
- Cancel manually or simulate a tab close
- View real-time logs of cancellation events

## Summary Checklist

- [x] Pass the `CancellationToken` through all async APIs
- [x] Only check/cancel in the service layer when needed
- [x] Never check in API or data layers, because framework code already handler
- [x] Log and handle `OperationCanceledException` for observability

## References

- [Microsoft Docs: Cancellation in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/cancellation)

---

For more C# and ASP.NET Core tips, check out other posts in this category!


Learn the best practices for using CancellationToken in ASP.NET Core Web APIs, with real-world code samples, client/server demos, and practical guidance for robust cancellation handling.

C# CancellationToken Best Practices for Web API


## Table of Contents

1. [Introduction](#introduction)
2. [DRY Design Principle](#dry-design-principle)
3. [SoC Design Principle](#soc-design-principle)
4. [DIE Design Principle](#die-design-principle)
5. [KISS Design Principle](#kiss-design-principle)
6. [YAGNI Design Principle](#yagni-design-principle)
7. [TDA Design Principle](#tda-design-principle)
8. [Conclusion](#conclusion)

## Introduction

This blog covers some of the most widely used design principles in software development. These principles help developers write code that is maintainable, testable, and scalable. Whether you are an experienced developer or just starting out, understanding these principles will improve the quality of your code.

The following design principles are covered in this post:

- **DRY** — Don't Repeat Yourself
- **SoC** — Separation of Concern
- **DIE** — Duplicate Is Evil
- **KISS** — Keep It Simple, Stupid
- **YAGNI** — You Ain't Gonna Need It
- **TDA** — Tell Don't Ask

## DRY Design Principle

**DRY** stands for **Don't Repeat Yourself**. This principle states that you should avoid repeating the same code in multiple places. If you find functions or code being used in multiple locations, it is better to move them to a common place. Otherwise, you will have to maintain the same code in two different spots.

This principle applies to any area of software development — whether you are structuring front-end SCSS files, creating JavaScript functions, or developing back-end SQL queries. Below is an example using Node.js with TypeScript.

### Example: Extracting Shared Constants

Imagine you are developing Page A and create a class that needs a readonly string for a blog detail URL, so you define it in Page A. Later, you notice that Page B also needs the same URL. Based on the DRY principle, you should move it to a common location that both classes can access — perhaps a constants file.

```typescript
// page A
private readonly BLOG_DETAIL: string = "/blog/post/";

// page B
private readonly BLOG_DETAIL: string = "/blog/post/";
```

### Example: SCSS Variables

The DRY principle also applies when creating SCSS files. If you declare a variable for your primary color in one SCSS file and that variable is needed in other SCSS files, it is better to declare it in a global variables file that all SCSS files can import.

### Example: Avoiding Duplicate Functions

I have seen cases where a developer creates one file for `localStorage` operations in JavaScript and another nearly identical file for `sessionStorage` operations. The only difference is `localStorage` versus `sessionStorage`, but the code ends up duplicated. This is a missed opportunity to apply the DRY principle.

The DRY principle may seem simple, but consistently keeping it in mind can lead to significant improvements. For instance, how do you share the same UI component across two different systems — one for a public-facing UI and another for an internal UI? Approaches like Micro Front-End architecture can help solve this type of problem while staying true to the DRY principle.

## SoC Design Principle

**SoC** stands for **Separation of Concern**. This principle is about dividing a software program into distinct sections or units, where each section has its own purpose. Following this principle leads to better maintainability, easier code refactoring, and improved testability.

Imagine if one class had to handle everything — it would be very difficult to understand, maintain, and debug.

### Example: Express.js Route

Let's look at the following code. This Express.js route takes a query string key, uses that value to query MongoDB for localization data, and then binds the data to a view called `local-view`. The code is not too long, follows the DRY principle, and appears to work. So what's wrong?

```javascript
const mongoose = require('mongoose');
const Schema = mongoose.Schema;

let local = new Schema({
        key: {
            type: String
        },
        value: {
            type: String
        },
        culture: {
            type: String
        }
});

async getLocalText(key) {
        if (!key) {
            return '';
        }

        try {
            return await localModel.findOne({key: key});

        } catch (error) {
            console.error(error);
            return '';
        }
    }

exports.all = async function(req, res) {

    const model = await getLocalText(req.params.key);

    res.render('local-view', model);

}
```

This code can be broken down into the following sections, each with its own responsibility:

- **Database Model** — Defines the MongoDB schema
- **Database Repository** — Repository function to access the MongoDB database
- **View Model** — Model to bind to the view
- **Controller** — Checks the request query, gets the model, and binds it to the view

### Why Separation Matters

What happens if you don't separate concerns? Your code becomes a "God class" — a class that does everything. God classes are hard to maintain, hard to add features to, hard to debug, and hard to test.

By creating a separate file for the database model, you can add validation and define the schema in one place that can be shared with other repositories. By creating a separate database repository file, that file only needs to handle database access and connections. The same goes for the view model and controller — each has its own focused purpose.

## DIE Design Principle

**DIE** stands for **Duplicate Is Evil**. This principle is similar to DRY but emphasizes that duplication is inherently harmful to code quality. When writing new code, you should actively work to eliminate duplicates.

However, there may be cases where you choose not to refactor duplicates, especially when other factors take priority.

### When to Refactor Duplicates

If you join a team and notice many duplicate constants or functions, should you change them? The answer depends on several factors:

- **Your error rate** — How likely are you to introduce bugs during refactoring?
- **QA automation** — Do you have a trusted automated test suite to catch regressions?
- **Team trust** — Does your team trust you to make refactoring changes safely?

If you are new to a company and immediately send a PR to refactor everything, it may go well if nothing breaks. But if you accidentally break something, it could take time to rebuild trust. Timing and context matter when applying this principle.

## KISS Design Principle

**KISS** stands for **Keep It Simple, Stupid**. This principle means keeping your software design as simple as possible and avoiding unnecessary complexity. While this sounds straightforward, writing simple code often takes more effort than writing complex code. You need to review your code repeatedly to find simpler approaches, reduce unnecessary logic, and test again.

### Example: Two Approaches to Bug Fixing

Consider a scenario where you need to fix a bug that seems complex. Developer A goes in and fixes the issue but creates several new functions in the process. Developer B fixes the same issue with just one line of code. Which approach is better?

Developer B likely spent more time understanding the root cause of the issue before writing any code. This brings us to a few practices that help maintain simplicity:

### Tips for Keeping It Simple

1. **Find the real problem first** — Invest time in understanding the issue before writing code. The reason Developer B needed only one line might be that they spent more time understanding the problem.

2. **Keep files small** — If a file is growing large, it likely contains mixed responsibilities. Breaking it into smaller, focused pieces helps maintain simplicity.

3. **Do code reviews** — Collaborate with your coworkers to review and simplify code. Pair programming and code reviews are great ways to write simpler, cleaner code.

## YAGNI Design Principle

**YAGNI** stands for **You Ain't Gonna Need It**. This principle is related to KISS and advises against adding functionality until it is actually needed. When designing software, keep it simple and avoid implementing features based on speculation about future requirements. If you don't need it now, don't build it now.

Adding unnecessary features increases complexity, creates more code to maintain, and can lead to bugs in features that may never be used. Focus on the current requirements and add new functionality only when there is a clear need for it.

## TDA Design Principle

**TDA** stands for **Tell, Don't Ask**. This principle suggests that an object should be responsible for its own data and behavior, rather than requiring the caller to query the object's state and perform calculations externally.

### Example: Before Applying TDA

In the following example, the caller creates a `LineItem` object and manually calculates the total:

```typescript
class LineItem {
  ItemPrice: number;
  Quantity: number;
  Total: number;
}

const myItem = new LineItem();
myItem.ItemPrice = 30;
myItem.Quantity = 2;
myItem.Total = 2 * 30;
```

### Example: After Applying TDA

Now, we refactor the code so the `LineItem` class calculates the total internally. The caller simply tells the object the price and quantity, and the object provides the total:

```typescript
class LineItem {
  constructor(itemPrice: number, quantity: number) {}
  get Total(): number {
    return this.itemPrice * this.quantity;
  }
}

const myItem = new LineItem(30, 2);
console.info(myItem.Total);
```

As a `LineItem` class grows with more logic and properties, it might make sense to separate its business logic and data properties into different files, continuing to apply other principles like SoC.

## Conclusion

Design principles are essential tools for writing high-quality software. Here is a summary of the six principles covered in this post:

| Principle | Full Name               | Key Takeaway                                       |
| --------- | ----------------------- | -------------------------------------------------- |
| **DRY**   | Don't Repeat Yourself   | Move shared code to a common location              |
| **SoC**   | Separation of Concern   | Each module should have one focused responsibility |
| **DIE**   | Duplicate Is Evil       | Actively eliminate code duplication                |
| **KISS**  | Keep It Simple, Stupid  | Write the simplest code that solves the problem    |
| **YAGNI** | You Ain't Gonna Need It | Don't build features you don't need yet            |
| **TDA**   | Tell, Don't Ask         | Objects should manage their own data and behavior  |

These principles are guidelines, not rigid rules. Apply them thoughtfully based on your project's context, and they will help you write more maintainable, testable, and scalable code.


A guide to widely used design principles in software development, including DRY, SoC, DIE, KISS, YAGNI, and TDA, with practical example code.

Design Principles in Software Development Part 1


## Table of Contents

- [SOLID Design Principle](#solid-design-principle)
- [Single Responsibility Principle (SRP)](#single-responsibility-principle)
- [Open/Closed Principle (OCP)](#openclosed-principle)
- [Liskov Substitution Principle (LSP)](#liskov-substitution-principle)
- [Interface Segregation Principle (ISP)](#interface-segregation-principle)
- [Dependency Inversion Principle (DIP)](#dependency-inversion-principle)
- [Conclusion](#conclusion)

## Introduction

This blog talks about design principles in software development. It will
focus on the SOLID design principles and provide a few example codes. This is
Part 2 of the Design Principles series, covering the five SOLID principles
that help developers build maintainable and scalable software.

## SOLID Design Principle

SOLID design principle is an acronym for the following five design principles.
These design principles will help you build maintainable, testable, flexible,
and understandable software applications.

### Single Responsibility Principle

> "There should never be more than one reason for a class to change. In other
> words, every class should have only one responsibility."

SRP, the Single Responsibility Principle, basically states that one class
should only have one purpose or responsibility. This is similar to SoC
(Separation of Concerns), with a slight difference. If we keep this principle
in mind, it will be very helpful for software design in any area. Let's look
at the following sample code.

Assume you start to use Express.js to write a blog system. The back-end is
MongoDB and you're using Node.js Mongoose as an ORM to access the MongoDB
database. The following is an Express.js route that takes an ID from the page,
then performs a query to the MongoDB database and returns the result to the UI.
The UI code is not shown here but will take the post data and display it on the
page.

This is not a lot of code, but it has several areas of concern. You see the
code to define the MongoDB schema, the setup for the index, a query to the
Posts collection by ID, and Express.js code to call the data for the UI. Based
on the Single Responsibility Principle, we should divide all these different
areas of code into separate files. One of the reasons is maintainability. I
know the following code is just a few lines, but in reality one page's code
could be hundreds or thousands of lines. It probably calls many different
services, validation, and filters to get the data. That's why when you first
write the code, it is better to keep this principle in mind and break the code
into different files.

Let's see how we change this code.

```
const mongoose = require('mongoose');
const Schema = mongoose.Schema;

const PostsSchema = new Schema({
   slug: String,
   title: String,
   state: String,
   content: String,
   createdDate: Date,
   tags: Array
});

PostsSchema.index({
   title: 'text',
   content: 'text'
});

async findById(id: any) {
    return this.PostsSchema.findById(id);
}

exports.index = async function(req, res) {

    const model = await findById(req.params.id);

    res.render('my-page-by-id', model);

}
```

posts.schema.ts

First, I think we can move the Posts MongoDB schema to a separate file. This
will be the file you update whenever you change your collection's MongoDB
schema or add some default index.

```
const mongoose = require('mongoose');
const Schema = mongoose.Schema;

export const PostsSchema = new Schema({
   slug: String,
   title: String,
   state: String,
   content: String,
   createdDate: Date,
   tags: Array
});

PostsSchema.index({
   title: 'text',
   content: 'text'
});
```

Posts.dataService.ts

For the MongoDB database access part, create another data repository file
as PostsDataService. This file will be responsible for accessing MongoDB
and returning the result.

```
const {PostsSchema} from './Posts.schema.ts';
export class PostsDataService {

   async findById(id: any) {
        return this.PostsSchema.findById(id);
   }
}
```

index.ts

Now, the last file is the Express.js route — the controller page that handles
page requests, gets data, and returns it to the view. Ideally, there should be
another business logic layer in between, but after removing the MongoDB schema
and data access, this file now has much less responsibility. It simply
validates the request and returns the data to the UI.

```
const {PostsDataService} from './Posts.DataService.ts';

exports.index = async function(req, res) {

   if (!req.params.id) {
       // go to 404 page
      return GoTo404Page();
   }

    const model = await new PostsDataService().findById(req.params.id);

    res.render('my-page-by-id', model);

}
```

### Open/Closed Principle

> "Software entities should be open for extension, but closed for
> modification."

The Open/Closed Principle states that when you create a class, you should hide
or close its implementation from the outside, but it should be open for others
to extend its functions. Let's take a look at the previous Posts DataService
class, this time with a few more functions added.

You'll also notice that you need to create comment, users, and image MongoDB
collections, and they all have similar functions as follows. You want them all
to use the same implementation to access the MongoDB database, but you also
want to extend the functions for each collection.

```
const {PostsSchema} from './Posts.schema.ts';
export class PostsDataService {

   async findById(id: any) {
        return this.PostsSchema.findById(id);
   }

    async countAllQuery(condition:any): Promise {
        return await this.PostsSchema.count(condition);
    }

    async deleteOne(model: any): Promise {
        return await this.PostsSchema.deleteOne(model);
    }

    async update(filter: any, doc: any) {
        return await this.PostsSchema.updateOne(filter, doc);
    }}
```

Let's check how we can achieve this.

IDataServiceBase.ts

First, create an interface which has all the functions you think all the other
collections can use.

```
export interface IDataServiceBase {

    create(model: Dto): Promise;
    findAll(sort?: object, filter?: object, limit?: number, skip?: number): Promise;
    findAllByModel(model: Collection): Promise;
    findOneById(id: any): Promise;
    findOne(model: Collection): Promise;
    countAll(): Promise;
    count(model: Collection): Promise;
    update(filter: Collection, doc: Collection);
    deleteOne(model: Collection): Promise;
}
```

DataServiceBase.ts

Next, we'll create a base data class to implement the interface. All the
detailed implementation goes inside this DataServiceBase class.

```
import { Document } from 'mongoose';
export abstract class DataServiceBase
implements InterfaceServiceBase {
    create(model: TModel): Promise {
        throw new Error("Method not implemented.");
    }
    findAll(sort?: object, filter?: object, limit?: number, skip?: number): Promise {
        throw new Error("Method not implemented.");
    }
    findAllByModel(model: TDocument): Promise {
        throw new Error("Method not implemented.");
    }
    findOneById(id: any): Promise {
        throw new Error("Method not implemented.");
    }
    findOne(model: TDocument): Promise {
        throw new Error("Method not implemented.");
    }
    countAll(): Promise {
        throw new Error("Method not implemented.");
    }
    count(model: TDocument): Promise {
        throw new Error("Method not implemented.");
    }
    update(filter: TDocument, doc: TDocument) {
        throw new Error("Method not implemented.");
    }
    deleteOne(model: TDocument): Promise {
        throw new Error("Method not implemented.");
    }
}
```

### Liskov Substitution Principle

> "Functions that use pointers or references to base classes must be able to
> use objects of derived classes without knowing it."

The Liskov Substitution Principle (LSP) means that objects of a subclass
should be able to replace objects of the parent class without breaking the
application. In other words, if class B is a subclass of class A, you should
be able to pass an instance of B anywhere an instance of A is expected, and
everything should still work correctly. This encourages designing class
hierarchies where derived classes truly extend the behavior of the base class
rather than altering it in unexpected ways. Violating LSP often leads to
fragile code that relies on type-checking or conditional logic to handle
different subclasses.

### Interface Segregation Principle

> "Many client-specific interfaces are better than one general-purpose
> interface."

ISP, the Interface Segregation Principle, is about making interfaces as small
as possible instead of having one big interface doing everything. If you use a
single large interface, you might end up with classes that implement methods
they don't actually need, leaving some declared but doing nothing.

Let's take a look at the following example. It is a data repository interface
which contains basic CRUD operations. Now, let's say you want to implement
some operations that only involve writing or reading. Would you create a class
that implements the full IDataServiceBase?

```
export interface IDataServiceBase {

    create(model: Dto): Promise;
    findAll(sort?: object, filter?: object, limit?: number, skip?: number): Promise;
    findAllByModel(model: Collection): Promise;
    findOneById(id: any): Promise;
    findOne(model: Collection): Promise;
    countAll(): Promise;
    count(model: Collection): Promise;
    update(filter: Collection, doc: Collection);
    deleteOne(model: Collection): Promise;
}
```

For that scenario, you should create interfaces only for what is needed. So I
separated IDataServiceBase into the following two interfaces. You can use each
interface to implement specific details in a separate class file.

```
export interface IWriteDataServiceBase {

    create(model: Dto): Promise;
    update(filter: Collection, doc: Collection);
    deleteOne(model: Collection): Promise;

}

export interface IReadDataServiceBase {

    findAll(sort?: object, filter?: object, limit?: number, skip?: number): Promise;
    findAllByModel(model: Collection): Promise;
    findOneById(id: any): Promise;
    findOne(model: Collection): Promise;
    countAll(): Promise;
    count(model: Collection): Promise;
}
```

You can also combine the two interfaces together if needed.

```
export interface IDataServiceBase
extends IReadDataServiceBase, IReadDataServiceBase {

}
```

### Dependency Inversion Principle

> "Depend upon abstractions, not concretions."

The Dependency Inversion Principle (DIP) states that high-level modules should
not depend on low-level modules. Both should depend on abstractions.
Additionally, abstractions should not depend on details; details should depend
on abstractions. In practice, this means that instead of a class directly
creating or referencing a concrete implementation, it should depend on an
interface or abstract class. This makes it easy to swap out implementations
without modifying the high-level code. For example, in the code we wrote
earlier, the Express.js controller depends on the PostsDataService class
directly. With DIP, you would have the controller depend on an
IDataServiceBase interface instead, allowing you to inject any implementation
at runtime.

## Conclusion

In this post, we covered the five SOLID design principles: Single
Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and
Dependency Inversion. Each principle helps you write cleaner, more
maintainable, and more flexible code. By applying SRP you keep classes
focused, OCP lets you extend behavior without modifying existing code, LSP
ensures subclasses are truly interchangeable, ISP keeps interfaces lean, and
DIP decouples high-level logic from low-level details. Keeping these
principles in mind from the start will save you significant effort as your
codebase grows.


This blog talks about design principles in software development. It includes SOLID and a few more widely used design principles, with example code.

Design Principles in Software Development Part 2


## Table of Contents

1. [Introduction](#introduction)
2. [Recommended Reading](#recommended-reading)
3. [The Bad Parts of JavaScript](#the-bad-parts-of-javascript)
4. [Understanding the `this` Keyword](#understanding-the-this-keyword)
5. [Scope and Hoisting](#scope-and-hoisting)
6. [Common JavaScript Pitfalls](#common-javascript-pitfalls)
7. [Type Coercion and Falsy Values](#type-coercion-and-falsy-values)
8. [Objects and Prototypes](#objects-and-prototypes)
9. [Functions: Statements vs Expressions](#functions-statements-vs-expressions)
10. [Best Practices](#best-practices)

## Introduction

ECMAScript 5 (ES5) introduced many improvements to JavaScript, but the language still retains some problematic features from its earlier versions. Understanding these quirks is essential for writing robust, maintainable code.

This memo covers the "bad" and "awful" parts of JavaScript as identified by Douglas Crockford, along with practical guidance on how to avoid common pitfalls.

## Recommended Reading

Essential resources for understanding JavaScript deeply:

- [Awful Parts: Appendix A - JavaScript: The Good Parts](http://archive.oreilly.com/pub/a/javascript/excerpts/javascript-good-parts/awful-parts.html)
- [Bad Parts: Appendix B - JavaScript: The Good Parts](http://archive.oreilly.com/pub/a/javascript/excerpts/javascript-good-parts/bad-parts.html)

## The Bad Parts of JavaScript

These features should be avoided or used with extreme caution:

### `with` Statement

The `with` statement was intended to provide shorthand for accessing object properties but creates ambiguity and performance issues.

```javascript
// Avoid this
with (obj) {
  a = b; // Is 'a' a property of obj or a global variable?
}

// Do this instead
obj.a = obj.b;
```

### `eval()` Function

`eval()` executes arbitrary strings as code, creating security vulnerabilities and performance problems.

```javascript
// Never do this
eval('var x = ' + userInput);

// Use JSON.parse for data
var data = JSON.parse(jsonString);
```

### `void` Operator

The `void` operator is confusing and rarely needed. It evaluates an expression and returns `undefined`.

```javascript
// Confusing
void 0; // returns undefined

// Clearer alternative
undefined;
```

### Type Coercion

JavaScript's implicit type conversion leads to unexpected behavior:

```javascript
// Surprising results
'5' + 3; // "53" (string concatenation)
'5' - 3; // 2 (numeric subtraction)
[] + {}; // "[object Object]"
{
}
+[]; // 0

// Use explicit conversion
Number('5') + 3; // 8
String(5) + '3'; // "53"
```

### `continue` and `switch` Fall-through

Both can create confusing control flow:

```javascript
// Always use break in switch
switch (value) {
  case 1:
    doSomething();
    break; // Don't forget this!
  case 2:
    doSomethingElse();
    break;
  default:
    doDefault();
}
```

## Understanding the `this` Keyword

The value of `this` in JavaScript depends on how a function is called. This is one of the most confusing aspects of the language.

### Method Invocation

When called as an object method, `this` refers to the object:

```javascript
var obj = {
  name: 'Object',
  getName: function () {
    return this.name; // 'this' is obj
  },
};

obj.getName(); // "Object"
```

### Using `call()` and `apply()`

Explicitly set `this` using `call()` or `apply()`:

```javascript
function greet(greeting) {
  return greeting + ', ' + this.name;
}

var person = { name: 'Alice' };

// Using call (arguments listed)
greet.call(person, 'Hello'); // "Hello, Alice"

// Using apply (arguments as array)
greet.apply(person, ['Hi']); // "Hi, Alice"
```

### Constructor Invocation with `new`

When using `new`, `this` refers to the newly created object:

```javascript
function Person(name) {
  this.name = name; // 'this' is the new instance
}

var alice = new Person('Alice');
console.log(alice.name); // "Alice"
```

### Arrow Functions (ES6+)

Arrow functions inherit `this` from their enclosing scope:

```javascript
var obj = {
  name: 'Object',
  delayedGreet: function () {
    // Arrow function preserves 'this'
    setTimeout(() => {
      console.log(this.name); // "Object"
    }, 100);
  },
};
```

## Scope and Hoisting

### Variable Hoisting

Variable declarations are "hoisted" to the top of their scope:

```javascript
function example() {
  console.log(x); // undefined (not ReferenceError)
  var x = 5;
  console.log(x); // 5
}

// Equivalent to:
function example() {
  var x; // Declaration hoisted
  console.log(x); // undefined
  x = 5; // Assignment stays in place
  console.log(x); // 5
}
```

### Function Hoisting

Function declarations are fully hoisted:

```javascript
sayHello(); // Works! "Hello"

function sayHello() {
  console.log('Hello');
}

// But function expressions are NOT hoisted
sayGoodbye(); // TypeError: sayGoodbye is not a function

var sayGoodbye = function () {
  console.log('Goodbye');
};
```

## Common JavaScript Pitfalls

### Global Variables

Undeclared variables become global:

```javascript
function badFunction() {
  x = 10; // Creates global variable!
}

// Always use var, let, or const
function goodFunction() {
  var x = 10; // Local variable
}
```

### Semicolon Insertion

JavaScript automatically inserts semicolons, sometimes incorrectly:

```javascript
// This returns undefined, not the object!
function getObject() {
  return;
  {
    name: 'value';
  }
}

// Correct way
function getObject() {
  return {
    name: 'value',
  };
}
```

### Reserved Words

Some words cannot be used as identifiers:

```javascript
// These will cause errors
var class = "CSS";   // Error
var return = 5;      // Error

// Object properties are safer but still problematic
var obj = {
  class: "CSS"       // Works in ES5+
};
```

### The `typeof` Operator

`typeof` has some quirks:

```javascript
typeof []; // "object" (not "array"!)
typeof null; // "object" (historical bug)
typeof function () {}; // "function"
typeof undefined; // "undefined"

// Use Array.isArray() for arrays
Array.isArray([]); // true
```

### `parseInt()` Issues

Always specify the radix:

```javascript
parseInt('08'); // 0 in older browsers (octal)
parseInt('08', 10); // 8 (always use radix!)
```

### Floating Point Precision

JavaScript uses IEEE 754 floating point:

```javascript
0.1 + 0.2; // 0.30000000000000004 (not 0.3!)

// For currency, use integers (cents)
var cents = 10 + 20; // 30
var dollars = cents / 100; // 0.30
```

### `NaN` (Not a Number)

`NaN` is not equal to itself:

```javascript
NaN === NaN; // false!

// Use isNaN() to check
isNaN(NaN); // true
Number.isNaN(NaN); // true (ES6, more reliable)
```

### The `+` Operator

The `+` operator is overloaded for addition and concatenation:

```javascript
5 + 3; // 8 (addition)
'5' + 3; // "53" (concatenation)
5 + '3'; // "53" (concatenation)

// Be explicit
5 + Number('3'); // 8
String(5) + '3'; // "53"
```

## Type Coercion and Falsy Values

### Falsy Values in JavaScript

These values evaluate to `false` in boolean context:

```javascript
false
0
"" (empty string)
null
undefined
NaN
```

### Truthy Gotchas

Some values are truthy but might surprise you:

```javascript
Boolean([]); // true (empty array)
Boolean({}); // true (empty object)
Boolean('0'); // true (non-empty string)
Boolean('false'); // true (non-empty string)
```

### Using `hasOwnProperty`

Always use `hasOwnProperty` when iterating:

```javascript
var obj = { a: 1, b: 2 };

for (var key in obj) {
  if (obj.hasOwnProperty(key)) {
    console.log(key, obj[key]);
  }
}
```

## Objects and Prototypes

### Prototype Inheritance

JavaScript uses prototypal inheritance:

```javascript
var animal = {
  speak: function () {
    console.log('Sound');
  },
};

var dog = Object.create(animal);
dog.speak = function () {
  console.log('Bark');
};

dog.speak(); // "Bark"
```

### `Object.create()` for Inheritance

Prefer `Object.create()` over constructor patterns:

```javascript
// Using Object.create (cleaner)
var parent = {
  greet: function () {
    return 'Hello';
  },
};

var child = Object.create(parent);
child.greet(); // "Hello"
```

## Functions: Statements vs Expressions

### Function Declaration (Statement)

```javascript
// Hoisted - can be called before declaration
sayHello();

function sayHello() {
  console.log('Hello');
}
```

### Function Expression

```javascript
// NOT hoisted - must be defined before use
var sayHello = function () {
  console.log('Hello');
};

sayHello();
```

### Named Function Expression

```javascript
// Useful for recursion and debugging
var factorial = function fact(n) {
  return n <= 1 ? 1 : n * fact(n - 1);
};
```

## Best Practices

### Avoid These Features

| Feature                         | Why Avoid                       | Alternative             |
| ------------------------------- | ------------------------------- | ----------------------- |
| `with`                          | Ambiguous scope                 | Direct property access  |
| `eval()`                        | Security risk                   | `JSON.parse()`          |
| `==`                            | Type coercion                   | `===` (strict equality) |
| `++`/`--`                       | Can be confusing                | `+= 1` or `-= 1`        |
| Bitwise operators               | Confusing in JS                 | Explicit operations     |
| Typed wrappers (`new String()`) | Creates objects, not primitives | Use literals            |

### Always Do These

1. **Use strict mode**: `"use strict";`
2. **Declare variables**: Always use `var`, `let`, or `const`
3. **Use `===`**: Avoid loose equality
4. **Specify radix**: `parseInt(str, 10)`
5. **Use semicolons**: Don't rely on automatic insertion
6. **Use `hasOwnProperty`**: When iterating with `for-in`

### Code Example: Modern ES5 Pattern

```javascript
'use strict';

var MyModule = (function () {
  // Private variables
  var privateVar = 'secret';

  // Private function
  function privateFunction() {
    return privateVar;
  }

  // Public API
  return {
    publicMethod: function () {
      return privateFunction();
    },
  };
})();

MyModule.publicMethod(); // "secret"
```

## Conclusion

ECMAScript 5 is a capable language, but understanding its quirks is essential for writing reliable code. Key takeaways:

1. **Avoid the "bad parts"**: `with`, `eval`, loose equality
2. **Understand `this`**: Know how function invocation affects `this`
3. **Be explicit**: Use strict equality, specify radix, declare variables
4. **Use strict mode**: Catches common mistakes early
5. **Learn prototypes**: Understand JavaScript's inheritance model

These practices will help you write cleaner, more maintainable JavaScript code.


A comprehensive guide to JavaScript quirks, pitfalls, and best practices based on Douglas Crockford's JavaScript - The Good Parts.

Best Practices

C# CancellationToken Best Practices for Web API

Design Principles in Software Development Part 1

Design Principles in Software Development Part 2

A Memo for ECMAScript 5 - The Good, Bad, and Awful Parts

Subscribe for Updates