Designing Before Coding

Overview

Write the design in pseudocode BEFORE writing implementation code. Iterate through multiple approaches in pseudocode, pick the best, THEN translate to code.

Core principle: Once you start coding, you get emotionally involved with your code and it becomes harder to throw away a bad design. Design is cheap to change; code is expensive.

Violating the letter of the rules is violating the spirit of the rules.

When to Use

Use for ANY programming task beyond trivial one-liners:

• New features or functionality
• Non-trivial bug fixes
• Refactoring
• Any routine longer than ~5 lines
• When you're unsure how to proceed
• When solution feels complex

Red flags that you need this:

• Jumping straight to implementation code
• "Just one more compile" syndrome
• Coding yourself into a corner
• Losing train of thought mid-implementation
• Forgetting to write parts of a routine
• Staring at screen not knowing where to start
• Code feels hack-y or patched together

Don't skip when:

• Under time pressure (designing first is FASTER than debug cycles)
• Problem seems simple (simple problems benefit from design too)
• You're confident you know the solution (overconfidence causes mistakes)

The Process

Step 1: Check Prerequisites

Before any design work:

• Is the job well-defined?
• Does it fit cleanly into overall design?
• Is it actually required by the project?
• What information will this routine hide?
• What are the inputs and outputs?
• What are preconditions (guaranteed true before routine called)?
• What are postconditions (guaranteed true after routine returns)?

If unclear, STOP. Get clarification before proceeding.

Step 2: Name the Routine

Name it BEFORE designing internals.

If you struggle to create a good name = WARNING SIGN.

• Vague name = vague design
• Wishy-washy name = wishy-washy purpose
• Can't name it clearly? Back up and clarify what it should do.

Good name = clear, unambiguous, describes what routine does.

Step 3: Think Through Error Handling

Before writing pseudocode:

• What could go wrong? (bad input, invalid return values, etc.)
• How will this routine handle errors?
• Does architecture define error strategy? Follow it.
• Which error approach: return neutral value, substitute valid data, log warning, return error code, throw exception, shut down?

Step 4: Research Libraries and Algorithms

Don't reinvent the wheel:

• Check standard libraries
• Check company/project libraries
• Check algorithm books if complex
• Reuse good code > writing from scratch

Step 5: Write High-Level Pseudocode

Use your code editor (it will become comments):

# Write general statement of purpose first
This routine outputs an error message based on an error code
supplied by the calling routine. The way it outputs the message
depends on the current processing state, which it retrieves
on its own. It returns a value indicating success or failure.

# Then write high-level pseudocode
set the default status to "fail"
look up the message based on the error code

if the error code is valid
   if doing interactive processing, display the error message
   interactively and declare success

   if doing command line processing, log the error message to the
   command line and declare success

if the error code isn't valid, notify the user that an internal
error has been detected

return status information

Pseudocode characteristics:

• Uses plain English, not programming language syntax
• Describes WHAT to do, not HOW to do it (intent, not implementation)
• High-level enough that you could implement in any language
• Low-level enough that translating to code is mechanical

Step 6: Review the Pseudocode

Critical step - don't skip:

• Read it mentally - does it make sense?
• Explain it to someone else (or imagine explaining it)
• Does it handle all cases?
• Is the logic clear?
• Are there edge cases missed?

…