Writing Implementation Pseudocode

Overview

Implementation pseudocode is actual TypeScript/JavaScript with strategic comments that help developers understand not just WHAT the code does, but WHERE it touches external systems (Boundary), HOW it integrates with dependencies (Integration), WHICH algorithm it uses (Pattern), and WHY it makes choices (Decision).

This style makes pseudocode directly translatable to production code while preserving architectural guidance.

When to Use

Use when:

• Adding pseudocode to implementation guides
• Documenting algorithms in technical specifications
• Showing method implementations in API documentation
• Creating code examples for developers who will implement

Don't use for:

• Abstract algorithm descriptions (use traditional pseudocode)
• User-facing documentation (use prose)
• Quick code sketches (use actual working code)

Required Elements

Every implementation pseudocode MUST include:

1. JSDoc header with Integration note
2. Strategic comments (Boundary/Integration/Pattern/Decision) for key operations
3. Section separators (---) for multi-phase algorithms
4. Actual TypeScript syntax (not abstract pseudocode)

Without these elements, pseudocode is incomplete.

Core Pattern

Before (Generic Comments)

extractBlock(anchorId: string): string | null {
  // Step 1: Find the block anchor in parsed anchors
  const anchor = this._data.anchors.find(a =>
    a.anchorType === 'block' && a.id === anchorId
  );

  // Not found? Return null
  if (!anchor) return null;

  // Step 2: Split content into lines
  const lines = this._data.content.split('\n');
  const lineIndex = anchor.line - 1;

  // Step 3: Validate line index
  if (lineIndex < 0 || lineIndex >= lines.length) {
    return null;
  }

  // Step 4: Extract and return line
  return lines[lineIndex];
}

After (Strategic Comments)

/**
 * Extract content for a specific block reference by anchor ID.
 * Integration: Uses anchor metadata from MarkdownParser output.
 *
 * @param anchorId - Block anchor ID without ^ prefix
 * @returns Single line content string or null if not found
 */
extractBlock(anchorId: string): string | null {
  // --- Anchor Lookup ---
  // Integration: Query anchors array from parser output
  const anchor = this._data.anchors.find(a =>
    a.anchorType === 'block' && a.id === anchorId
  );

  // Decision: Return null if block anchor not found (edge case handling)
  if (!anchor) return null;

  // --- Line Positioning ---
  // Boundary: Split raw content into lines for line-based extraction
  const lines = this._data.content.split('\n');
  const lineIndex = anchor.line - 1;  // Pattern: Convert 1-based to 0-based indexing

  // Decision: Validate line index within bounds (edge case handling)
  if (lineIndex < 0 || lineIndex >= lines.length) return null;

  // --- Content Extraction ---
  return lines[lineIndex];
}

Quick Reference

Strategic Comment Types

Boundary

Marks where code crosses system boundaries (file I/O, network, database, external data access).

// Boundary: Direct access to encapsulated raw content
return this._data.content;

// Boundary: Split raw content into lines for line-based extraction
const lines = this._data.content.split('\n');

Integration

Shows how code integrates with external libraries, frameworks, or components.

// Integration: Uses marked.js token tree for structural navigation
const walkTokens = (tokenList) => { ... };

// Integration: Query anchors array from parser output
const anchor = this._data.anchors.find(...);

Pattern

Identifies the algorithm, data structure, or design pattern being used.

// Pattern: Child-before-sibling traversal ensures in-order token collection
if (token.tokens) walkTokens(token.tokens);

// Pattern: Convert 1-based to 0-based indexing
const lineIndex = anchor.line - 1;

Decision

Explains why code makes a particular choice, especially for edge cases and branching.

// Decision: Return null if target heading not found (edge case handling)
if (targetIndex === -1) return null;

// Decision: Validate line index within bounds (edge case handling)
if (lineIndex < 0 || lineIndex >= lines.length) return null;

Section Separators

Use semantic names, not step numbers:

// ❌ Bad: Generic step numbers
// Step 1: Find anchor
// Step 2: Split lines
// Step 3: Validate
// Step 4: Extract

// ✅ Good: Semantic section names
// --- Anchor Lookup ---
// --- Line Positioning ---
// --- Content Extraction ---

For multi-phase algorithms, use phase names:

// --- Phase 1: Token Walking & Target Location ---
// --- Phase 2: Boundary Detection ---
// --- Phase 3: Content Reconstruction ---

JSDoc Headers

Always include:

• Purpose: What the method does
• Integration note: Key external dependencies
• @param: Parameter descriptions
• @returns: Return value description

/**
 * Extract content for a specific section by heading text and level.
 * Integration: Uses marked.js token tree for structural navigation.
 *
 * @param headingText - Exact heading text to find
 * @param headingLevel - Heading depth (1-6)
 * @returns Section content string or null if not found
 */

Inline Comments

Use for brief explanations that fit on one line:

const lineIndex = anchor.line - 1;  // Pattern: Convert 1-based to 0-based
if (targetIndex === -1) return null;  // Not found? Return null

Grouping Operations

Group related operations under section headers:

// --- Anchor Lookup ---
const anchor = this._data.anchors.find(a =>
  a.anchorType === 'block' && a.id === anchorId
);
if (!anchor) return null;

// --- Line Positioning ---
const lines = this._data.content.split('\n');
const lineIndex = anchor.line - 1;
if (lineIndex < 0 || lineIndex >= lines.length) return null;

// --- Content Extraction ---
return lines[lineIndex];

Red Flags - STOP and Add Strategic Comments

If your pseudocode has any of these, it's incomplete:

• ❌ No Boundary/Integration/Pattern/Decision comments
• ❌ Using "Step 1, Step 2, Step 3" labels
• ❌ No --- section separators for multi-phase algorithms
• ❌ JSDoc missing Integration note
• ❌ No strategic comments on key operations

All of these mean: Add strategic comments now.

Common Mistakes

When Strategic Comments Add Value

Use strategic comments when:

• Code crosses boundaries (file I/O, network, DB)
• Code integrates with external systems/libraries
• Algorithm choice matters (binary search, traversal pattern)
• Edge case handling needs explanation
• Index conversions happen (1-based to 0-based)

Don't overuse:

// ❌ Too many strategic comments
// Integration: Uses JavaScript array method
const items = array.filter(x => x.active);

// ✅ Only when it adds value
// Integration: Uses marked.js token tree for structural navigation
const tokens = marked.lexer(content);

Real-World Impact

Before (baseline test result):

• Generic step numbers
• No architectural context
• Developer has to infer integration points
• Missing boundary markers

After (with strategic comments):

• Clear section organization
• Explicit integration points marked
• Boundary crossings identified
• Pattern choices documented
• Decision rationale explained

Developers can implement faster because they know WHERE code touches external systems, HOW it integrates, WHICH patterns to use, and WHY decisions were made.