| purpose | canonical | version | type |
|---|---|---|---|
Define a concise pseudocode style for stubbing complex orchestration logic |
true |
1 |
concept |
A concise style for writing algorithm stubs that emphasize data transformations over control flow, using indentation for scope and set operations over loops.
Functional-Relational Pseudocode is a comment-based notation for stubbing complex orchestration logic. It lives in // TODO blocks within method bodies, describing what should happen (data flows, transformations, set operations) rather than how (loops, conditionals, state mutations). Use it when designing multi-step processes that coordinate multiple aggregates or modules.
Use indentation to show nesting (loops, conditionals, transactions). No closing markers (end, }). Each level represents a nested operation or scope.
Describe operations on collections as wholes: "Group stdIds by masterId", "Filter updates where keyChanges", "Extract unique masterIds". Avoid explicit iteration (for each item).
Use declarative verbs: Extract, Build, Map, Group, Query, Detect. Avoid imperative verbs: Set, Increment, Loop, Call (unless invoking a specific module method).
Use → or "maps to" for logic branches: "MINT → new UUID, LINK → targetMasterId". Avoid nested if/else blocks.
Define structures inline using JSON-like notation: { sourceMasterId, targetMasterId, reason: "auto_merge" }. No separate type definitions.
Hand-wave complex implementation details if logical intent is clear: "Apply state patches", "Process through Master Record Aggregate". Implementation fills the gaps.
❌ Bad (Imperative)
// Loop through all requests
// For each request:
// If request has candidates:
// Call scoreCandidates()
// Call decideBatch()
// Set bindingMap[stdId] = masterId
✅ Good (Functional-Relational)
// Accumulate sourceRecordResults: created + updated (skip passed)
// For each sourceRecordResult:
// If candidates exist:
// Score candidates via matchDecisionModule.scoreCandidates(...)
// Decide batch via matchDecisionModule.decideBatch(...)
// Update bindingMap: MINT → new UUID, LINK → targetMasterId
❌ Bad (Command Style)
// Create empty map
// Get all masterIds from bindingMap
// For each masterId:
// Query database
// Add to map
// Return map
✅ Good (Query Style)
// Extract unique masterIds from bindingMap values
// Query mdm_<entity> for each masterId
// Build preloadedMasters map: masterId → master entity
// Return preloadedMasters
❌ Bad (Nested Conditionals)
// For each stdId in bindingMap:
// Get desired masterId
// Get current masterId from preloadedMasters
// If desired != current:
// If multiple stdIds have same desired:
// Detect merge
✅ Good (Set-Based Detection)
// Detect merges: same desired group (bindingMap values), different current masters (from preloadedMasters)
// Group stdIds by desired masterId from bindingMap
// For each group, compare current masterIds from preloadedMasters
// If multiple distinct current masters → merge detected
// Identify canonical master: oldest createdAt becomes targetMasterId
Use These Verbs: Extract, Build, Map, Group, Query, Detect, Identify, Accumulate, Compare, Transform
Avoid These Verbs: Set, Increment, Loop, Iterate, Call (unless module method), Create empty, Initialize
Indentation Pattern:
// Top-level operation
// Nested operation
// Deeply nested operation
// Back to nested level
Common Patterns:
- Grouping:
Group X by Y from Z - Filtering:
Extract X where condition - Mapping:
Build map: key → value - Transformation:
Transform X into Y via operation
Place pseudocode in // TODO: Implement in Task X.Y comment blocks within stubbed method bodies. Follow with throw new Error('Not implemented yet - Task X.Y'). The pseudocode serves as the design blueprint for implementation.