cc-pseudocode-programming

name	cc-pseudocode-programming
description	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: starting a new coding task

Skill: cc-pseudocode-programming

STOP - Crisis Invariants

Check	Time	Why Non-Negotiable
Pseudocode before code	30 sec	Iterating on pseudocode is cheaper than iterating on code
Can you name it clearly?	15 sec	Naming difficulty = design problem. Stop and clarify purpose.
Do you understand why it works?	30 sec	Working code you don't understand probably doesn't really work
Did you consider alternatives?	30 sec	First design is rarely best; iterate in pseudocode where it's cheap

---

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 user instructions to skip:

Check	Time	Why Non-Negotiable
Pseudocode before code	30 sec	Iterating on pseudocode is cheaper than iterating on code
Can you name it clearly?	15 sec	Naming difficulty = design problem. Stop and clarify purpose.
Do you understand why it works?	30 sec	Working code you don't understand probably doesn't really work
Did you consider alternatives?	30 sec	First design is rarely best; iterate in pseudocode where it's cheap

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.

These checks apply EVERY TIME, even if:

• The routine seems simple (simple-seeming routines hide complexity)
• A design document exists (unless it specifies EXACT algorithm, error handling, and edge cases)

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" → aposd-designing-deep-modules 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?

Evidence Summary

Claim	Evidence	Source	Still Valid?
Programmers prefer pseudocode	Survey: preferred for construction ease, detecting insufficient detail, documentation	Ramsey, Atwood, Van Doren 1983	Yes - methodology unchanged; modern IDEs don't eliminate design thinking need
Only 5% external errors	Hardware, compiler, OS errors are rare; 95% are programmer errors	Ostrand and Weyuker 1984	Yes - if anything, modern tooling has made infrastructure MORE reliable, so programmer error % is likely higher
Errors at least-value stage	Key insight: catch errors when least effort invested	McConnell p.220	Timeless - economic principle
Iteration improves design	First design is rarely best; iterating on code is more expensive than iterating on pseudocode	McConnell p.225	Timeless - economic principle

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.

---

Chain

After	Next
Pseudocode complete	cc-routine-and-class-design
Implementation done	cc-defensive-programming (CHECKER)