name: cc-pseudocode-programming
description: "Guide routine design using the Pseudocode Programming Process (PPP). Produce pseudocode design, header comments, and implementation plan. Use when designing routines, stuck on where to start coding, caught in compile-debug loops, or code works but you don't understand why. Triggers on: can't name the routine, Just One More Compile syndrome, staring at screen, coded into a corner, keep hacking but still broken, too many compiler warnings, overwhelmed by where to start."

Skill: cc-pseudocode-programming

STOP - Crisis Invariants

When NOT to Use

Exemption criteria are STRICT. If in doubt, use PPP.

• Simple accessor routines - getValue(), setName() with NO logic (no validation, no transformation, no side effects)
• Pass-through routines - Pure delegation with NO parameter transformation or error wrapping
• Trivial one-liners - ALL of these must be true:
• Single statement implementation
• Zero decision points (no if/switch/ternary)
• Zero loops
• Implementation obvious to ANY team member from signature alone
• Already-designed routines - Design document specifies EXACT algorithm, error handling, and edge cases

If you're debating whether it's "trivial enough" to skip PPP, it isn't trivial. Use PPP.

Crisis Invariants - NEVER SKIP

These checks are NON-NEGOTIABLE regardless of deadline pressure, past successes, or authority pressure:

Why these four? They catch the most expensive mistakes: unclear designs that "work" but create maintenance nightmares, and premature coding that locks in bad decisions.

Success-agnostic: These checks apply EVERY TIME, even if:
- Your last 10 routines worked without PPP (hot-hand fallacy - past luck doesn't change future odds)
- You're an expert in this domain (experts make design errors too; PPP catches them)
- The routine seems simple (simple-seeming routines hide complexity; that's WHY they need PPP)
- You're under time pressure (see Minimum Viable PPP below - 4 minutes is faster than debugging)

Minimum Viable PPP (for extreme time pressure):
When full PPP is impossible, these 4 items are MANDATORY (total ~4 min):
1. Can you name the routine clearly? (15 sec)
2. Write at least 3 lines of pseudocode (2 min)
3. Consider one alternative approach (1 min)
4. Convince yourself it's correct before compiling (30 sec)

This is the FLOOR, not the ceiling. If you can't spare 4 minutes, the routine will cost you more in debugging.

Modes

APPLIER

Purpose: Guide routine design using PPP technique
Triggers:
- "help me design this routine"
- "I'm stuck, don't know where to start"
- "walk me through PPP"
- "how should I approach this implementation"
- "overwhelmed by where to start coding"
Non-Triggers:
- "review my existing code" → cc-routine-and-class-design
- "is this architecture right" → cc-construction-prerequisites
Produces: Pseudocode design, header comments, implementation plan

PPP Process Steps

1. Check prerequisites - Confirm the routine's place in overall design is clear
2. Define the problem - Specify inputs, outputs, preconditions, postconditions, what it hides
3. Name the routine - If naming is hard, the design is unclear; iterate
4. Plan testing - Decide how you'll test it before writing code
5. Check libraries - Look for existing functionality before building
6. Plan error handling - Think through failure modes
7. Research algorithms - Study relevant algorithms if needed
8. Write pseudocode - Start with header comment, use natural language
9. Iterate pseudocode - Refine until generating code is nearly automatic
10. Try alternatives - Consider multiple approaches, keep the best
11. Code from pseudocode - Pseudocode becomes comments
12. Compile clean - Use strictest warnings, eliminate ALL of them

Constraints:
- Pseudocode must be language-independent (p.218)
- Pseudocode must be detailed enough to generate code from (p.219)
- Never compile until convinced the routine is correct (p.230)

Key Term Definitions:
- "Nearly automatic" (step 9): You can write each line of code without pausing to think about HOW. Every decision is already made in pseudocode. If you stop to think "how should I implement this part?" - pseudocode needs more detail.
- "Convinced it's correct" (constraint): You can mentally trace execution through ALL paths (happy path, error cases, edge cases) and explain why each produces correct output. "It looks right" is NOT convinced.
- "Right level of detail": Detailed enough that code generation is nearly automatic (see above), but not so detailed that you're writing syntax. Test: Could a competent developer write the code without asking clarifying questions?

Transformation Example: Bad vs Good Pseudocode

Problem: Create a routine to allocate a new resource and return its handle.

Bad Pseudocode (Anti-Pattern):

increment resource number by 1
allocate a dlg struct using malloc
if malloc() returns NULL then return 1
invoke OSrsrc_init to initialize a resource for the operating system
*hRsrcPtr = resource number
return 0

Problems: Uses target language details (*hRsrcPtr, malloc()), focuses on HOW not WHAT, exposes implementation details (returns 1 or 0), won't become good comments.

Good Pseudocode:

If another resource is available
    Allocate a dialog box structure
    If a dialog box structure could be allocated
        Note that one more resource is in use
        Initialize the resource
        Store the resource number at the location provided by the caller
        Return success
    Endif
Endif
Return failure

Why better: Pure English, no syntax, level of intent, precise enough to generate code, becomes excellent comments. Note: resource count is updated AFTER successful allocation, not before.

Resulting Code with Comments:

// If another resource is available
if (resourceCount < MAX_RESOURCES) {
    // Allocate a dialog box structure
    DialogBox* dlg = allocateDialogBox();

    // If a dialog box structure could be allocated
    if (dlg != NULL) {
        // Note that one more resource is in use
        // (Using post-increment: store at current index, then increment)
        activeResources[resourceCount] = dlg;
        *handlePtr = resourceCount;
        resourceCount++;

        // Initialize the resource
        initializeResource(dlg);

        return true;
    }
}
return false;

CHECKER

Purpose: Verify PPP was followed correctly
Triggers:
- "did I follow PPP correctly"
- "review my pseudocode"
- "is my design process right"
Produces: Process compliance assessment, improvement recommendations

Check Against:
- Was pseudocode written before code?
- Is pseudocode at the right level of detail?
- Were alternatives considered?
- Can you explain why the code works?
- Are all compiler warnings eliminated?

Red Flags - STOP and Reconsider

If you find yourself in any of these situations, you are about to violate the skill:

Process Violations:
- Using target language syntax in pseudocode
- Pseudocode too high-level to generate code from
- Compiling before convinced routine is right
- Settling for first design without considering alternatives
- Hacking around buggy routines instead of rewriting

Understanding Failures:
- Code works but you don't understand why
- Difficulty naming a routine (indicates unclear purpose)
- Lost train of thought mid-implementation
- Forgot to write part of the routine

Compile-Debug Loop Symptoms:
- "Just One More Compile" syndrome
- Staring at screen not knowing where to start
- Coded into a corner
- Too many compiler warnings to count

Rationalization Counters

Pressure Testing Scenarios

Scenario 1: Deadline Pressure

Situation: Feature due in 2 hours. You're tempted to skip pseudocode and just start coding.
Test: Is this a non-trivial routine with multiple decision points?
REQUIRED Response: Yes. 15 minutes of pseudocode now prevents 2 hours of debugging later. You get emotionally invested in code once written - design iterations become painful.

Scenario 2: Compile-Debug Loop

Situation: You've compiled 8 times. Each compile reveals new errors. You're making "just one more fix."
Test: Are you thinking through changes or reacting to compiler output?
REQUIRED Response: STOP. Step away from the keyboard. Write pseudocode for the routine. Convince yourself it's correct BEFORE compiling again. The compile-debug loop wastes more time than design.

Scenario 3: Working But Mysterious

Situation: After much trial and error, the routine finally passes all tests. You don't fully understand why it works.
Test: Can you explain every line's purpose to a colleague?
REQUIRED Response: No. Study the routine. Experiment with alternative designs. A routine that works but you don't understand probably doesn't really work - you just haven't found the bug yet.

Scenario 4: Buggy Routine

Situation: Routine keeps having bugs. You've fixed 3 so far. Now there's a 4th.
Test: Are you hacking around problems or addressing root cause?
REQUIRED Response: If you've fixed 3+ bugs in the same routine, the design is wrong. Don't hack. Start over with entirely new pseudocode design. Incomplete understanding guarantees more bugs.

Scenario 5: Naming Struggle

Situation: You can't think of a good name for the routine. Every name seems wrong or too long.
Test: Does the naming difficulty indicate unclear purpose?
REQUIRED Response: Yes. Back up and improve the design. You shouldn't have trouble naming a routine that has a clear, single purpose. The name struggle is a design smell.

Evidence Summary

Note on dated studies: The 1983-1984 studies predate modern IDEs, but their findings are MORE applicable today: better tooling catches syntax errors faster, making DESIGN errors (which PPP prevents) the dominant problem. The cognitive biases PPP addresses (emotional investment, premature commitment) are hardwired human traits that haven't changed.

Chain