ape-write-pseudocode

Pseudocode Style Guide

Structure of a Function

Every pseudocode function has exactly three parts: input, output, and body. Use Python-like syntax: def for the function signature, a docstring-style comment block for input and output, and indented body lines.

def function_name(param1, param2, ...):
    # input:  <what each param represents>
    # output: <what the function returns or produces>

    <body>

Body Rules

The body is the core of the pseudocode. Each line describes one logical step at a very high level -- what the step takes as input and what it produces as output. Do not write code. Do not spell out implementation details.

• One line per logical step.
• Each line states what it receives and what it produces or decides.
• No variable declarations, no type annotations, no language syntax.
• No method chains, no intermediate variable names unless a name is essential to connect two steps.
• Never more than one idea per line.

Control Flow

Use if, elif, else, and loops sparingly and only when the branching or iteration is the point of the logic. Use Python-like keywords and colon-terminated headers.

if <condition>:
    <what happens>
else:
    <what happens instead>

for each <item> in <collection>:
    <what is done with item>

while <condition>:
    <what is repeated>

Keep conditions at the same high level as the rest of the body -- describe the condition in plain words, not code.

What to Write on Each Line

Each line should answer: "given what input, produce or decide what output?"

Good patterns:

• filter nodes by reachability from source
• sort entries by timestamp, oldest first
• compute shortest path from source to each node
• pick the candidate with the highest score
• merge left result and right result into sorted list

Bad patterns (too much detail):

• dist[v] = dist[u] + weight(u, v) -- this is code
• initialize a min-heap priority queue with (0, source) -- implementation detail
• list.stream().filter(x -> x > 0).collect(...) -- this is definitely code

Examples

Good:

def lsm_write(key, value):
    # input:  key and value to store
    # output: acknowledgement that write is recorded

    append key-value pair to memtable
    if memtable exceeds size threshold:
        flush memtable to a new SSTable on disk
        clear memtable

def lsm_read(key):
    # input:  key to look up
    # output: value for key, or not found

    check memtable for key
    if found in memtable:
        return value from memtable
    for each SSTable from newest to oldest:
        check bloom filter for key
        if bloom filter says key may exist:
            search SSTable for key
            if found:
                return value
    return not found

def lsm_compact(sstables):
    # input:  list of SSTables to merge
    # output: single merged SSTable with duplicates resolved

    open a cursor on each SSTable
    while any cursor has remaining entries:
        pick the entry with the smallest key across all cursors
        if same key appears in multiple SSTables:
            keep only the entry from the newest SSTable
        write chosen entry to output SSTable
    return output SSTable

Bad (do not do this):

def lsm_write(key: str, value: bytes):  # typed signature -- not pseudocode
    self.lock.acquire()
    self.memtable[key] = value          # this is Python code, not pseudocode
    if len(self.memtable) > self.threshold:
        self.flush()
    self.lock.release()

Checklist Before Writing

• Does each line describe logic, not implementation?
• Can a non-programmer read each line and understand what is happening?
• Are if/else and loops used only where branching or iteration is the actual point?
• Is every line a single idea?

If yes, the pseudocode is done.