Quantifying Code “Understandability” Part 1: Bounded Contexts

Finding the Context Boundary

Basic Examples of Bounded Context

A Function

// a pure function
function increment(count) {
  return count + 1;
}

function login(username, password) {
    if areValidUserCredentials(username, password) {
        return initialiseSession(username);
    }

    throw Exception('Invalid user credentials');
}

function areValidUserCredentials (username, password) {
    const user = getUserByUsername(username);
    return password === decrypt(user.passwordHash)
}

A Source File

// sourceFile.js
let globalVar = "Hello World";
console.log(globalVar)

// sourceFile.js
let globalVar = "Hello World";
console.log(globalVar)

/* Lots of unrelated code
	...
	...
*/

globalVar = "Mutated Hello World"; // ❌ developers need to scan everything to find this

A Class

class ExampleClass {
  private value = 42;

  doSomething() {
    // References 'this.value' => belongs to the class's scope
    this.value++;

    // A nested arrow function referencing 'this.value'
    const nested = () => {
      // Because it reads 'this.value', it merges with doSomething() as well
      return this.value * 2;
    };

    // Another nested arrow function (pure) doesn't reference outer scope
    const pureNested = (x: number) => x + 10;
    

    return { nested, pureNested };
  }
  
  doSomethingElse() {
	  pureFunction(this.value) // bounded context ends here
  }
  
  // ==================
  // BOUNDED CONTEXT 2
  static pureFunction(msg: string) {
	  console.log(msg)
  }
  // BOUNDED CONTEXT 2
  // ==================
}

Contaminating Bounded Contexts

function login(username, password) {

		function areValidUserCredentials () {
				// INNER FUNCTION IS IMPURE
		    const user = getUserByUsername(username);
		    return password === decrypt(user.passwordHash)
		}

    if areValidUserCredentials(username, password) {
        return initialiseSession(username);
    }

    throw Exception('Invalid user credentials');
}

// file-a.js
export let COUNT = 0

function increment() {
	COUNT++
}

// nasty code here
setTimeout(() => { COUNT++ }, 30000)


// file-b.js
import { COUNT } from './file-a'

COUNT++

// must read file-a to understand the unexpected result
setTimeout(() => { console.log(COUNT) }, 50000);

let COUNT = 0

// BY CALLING f1, WE EVENTUALLY CALL f3, WHICH IS CONTAMINATED BY THE GLOBAL SCOPE
function f1 () {
	// ...
	f2()
}

function f2 () {
	// ...
	f3()
}

function f3 () {
	COUNT++
}

let STATE = { count: 0 }

function f1 (state) {
	// ...
	state.num +=1 // ❌ MUTATION: THIS CONTAMINATES THE CONTEXT
}

f1(STATE)

Possible Bounded Context Containers in TypeScript

• Source File: Any code placed at the top level of a .ts file can be considered one “container,” especially if it declares and owns top-level variables or logic.

// sourceFile.ts

console.log("Top-level code here.");

// Perhaps some variables or imports, exported functions, etc.
const globalVar = 42;

function topLevelFunction() {
  // ...
}

• Arrow Function: A concise function form often assigned to a variable or used inline.

const greet = (name: string): string => {
  return `Hello, ${name}`;
};

• Function Expression: Similar to an arrow function but uses the classic function keyword. Can be anonymous or named.

const greet = function(name: string): string {
  return `Hello, ${name}`;
};

• Function Declaration: named function defined at any scope (usually top-level or nested).

function greet(name: string) {
  return `Hello, ${name}`;
}

• Object Literal Methods:

const obj = {
  foo() { /* ... */ },
  bar: function() { /* ... */ },
  baz: () => { /* ... */ }
};

• Class Declaration: Represents a blueprint for objects; can own state (this.value) and methods.

class ExampleClass {
  // class-level fields
  private value = 42;

  methodName() {
    // ...
  }

  constructor() {
    // ...
  }
}

• Method Declaration (typically static): A method can be its own container if it is pure–otherwise it defaults back to the class declaration context container.

class ExampleClass {

  static doSomething() {
    // ...
  }
}

• Module Declaration (namespaces): A legacy TS style (“internal modules”) – can contain variables, functions, classes. Often acts as a single container.

namespace MyNamespace {
  export const x = 123;

  export function doStuff() {
    return x + 1;
  }
}

• Static Blocks (Class static initialisation blocks): TS 4.6+ supports static { /* ... */ } in class declarations, which might hold logic and references.

class WithStaticBlock {
  static counter = 0;

  static {
    // Runs once on class loading
    this.counter = 100;
  }
}

let outerGlobalVar = 0; // not referenced in try/catch
//...
	try {
		// this is similar to a pure function
		let count = 0;
		increment(count);
		increment(count);		
	} catch {
		// another potential bounded context
	}

//...

In Practice, an Algorithm to Identify Bounded Contexts

1. Start with the TypeScript AST

2. Identify all the possible (nested) containers for a bounded context

3. Start at the child nodes of the containers (i.e. highest depth)

4. For each child of the container (line of code), find the “ownership” of each inner statement (i.e. looking for variable mutation)

5. If a child is owned by an outer container, eliminate the child and attach it to the highest shared node of ownership

6. Work upwards through the nodes from highest-depth first repeating steps 4 and 5 until no more eliminations of candidate bounded contexts are possible

function login(username, password) {

		function decrypt(pass) {
			return lib.decrypt(pass)
		}

		function areValidUserCredentials () {
		    const user = getUserByUsername(username);
		    return password === decrypt(user.passwordHash)
		}

    if areValidUserCredentials(username, password) {
        return initialiseSession(username);
    }

    throw Exception('Invalid user credentials');
}

1. The AST (just for containers) may look something like this:

2. We have identified the 3 possible bounded contexts.

3. Starting at the deepest child (either of the two inner functions).

4. For areValidUserCredentials, we look through each line and see in the first statement, ownership over username is in login.

5. We eliminate areValidUserCredentials as a possible bounded context (after seeing no other ownerships that are higher in the AST than login) and this context merges with that of login.

6. Repeating this for decrypt, which is a pure function, we only see local state, so this can remain as a bounded context.

{
	"function-areValidUserCredentials-<HASH>": {
		"context-declaration-file-name": "a/b/c.ts",
		"context-declaration-line": 5,
		"context-source-locations": [ { "file": "...", "line": 0 }, ...],
		"node": {...},
	},
	"function-decrypt-<HASH>": {
		"context-declaration-file-name": "a/b/c.ts",
		"context-declaration-line": 10,
		"context-source-locations": [...],
		"node": {...},
	}
}

Measuring and Optimising Bounded Context as a Heuristic