Skip to content
CodeCloom
Menu

Concept · code walkthroughs

Explain the code in the order it should be read.

CodeCloom is planned for the moment someone new asks “where do I start?” — a tour pinned to real lines, not a wiki page that drifts.

Take the sample tour

01The problem

Code is read in one order and written in another

A newcomer opens the repository at the alphabet's first folder. The author would have started three files deeper.

  1. Step 1

    Pick the path

    Choose the files and lines that tell the story of one feature.

  2. Step 2

    Pin the notes

    Attach short explanations to exact lines, in reading order.

  3. Step 3

    Share the tour

    A reader steps through it next to the real code.

02What it looks like

A four-step tour of a payment charge

Step through the sample. Each scene highlights the line the note is pinned to.

01The entry point

Start where the request lands

charge() is the only function the checkout calls. Everything else in the file supports it.

payments/charge.ts · step 1 of 4 · illustrative
  1. 1export async function charge(order) {
  2. 2 const key = idempotencyKey(order.id);
  3. 3 const res = await psp.charge(order.total, { key });
  4. 4 if (res.status === 'declined') throw new Declined(res);
  5. 5 return res.id;
  6. 6}
02Why the key comes from the order

Retries must not charge twice

Retries reuse the same idempotency key, so a timeout followed by a retry cannot charge twice.

payments/charge.ts · step 2 of 4 · illustrative
  1. 1export async function charge(order) {
  2. 2 const key = idempotencyKey(order.id);
  3. 3 const res = await psp.charge(order.total, { key });
  4. 4 if (res.status === 'declined') throw new Declined(res);
  5. 5 return res.id;
  6. 6}
03Calling the provider

One call, one key

The key travels with the request; the provider uses it to ignore duplicates.

payments/charge.ts · step 3 of 4 · illustrative
  1. 1export async function charge(order) {
  2. 2 const key = idempotencyKey(order.id);
  3. 3 const res = await psp.charge(order.total, { key });
  4. 4 if (res.status === 'declined') throw new Declined(res);
  5. 5 return res.id;
  6. 6}
04When the provider declines

A typed failure, not a string

Declined carries the provider's response so the caller can show the right message.

payments/charge.ts · step 4 of 4 · illustrative
  1. 1export async function charge(order) {
  2. 2 const key = idempotencyKey(order.id);
  3. 3 const res = await psp.charge(order.total, { key });
  4. 4 if (res.status === 'declined') throw new Declined(res);
  5. 5 return res.id;
  6. 6}

03Who it's for

Who it is being designed for

  • Onboarding

    A first-week tour through the paths that matter most.

  • Code review

    Context for a large change, in the order the author intended.

  • Teaching

    Lessons built on real, runnable code rather than snippets.

04At a glance

The pieces of a CodeCloom walkthrough.

A tour

  • PathFiles in reading order
  • NotesPinned to exact lines
  • StepsOne idea at a time
  • ReadersStep through beside the code
Infographic of planned parts; nothing here is a working feature yet.

05Honest status

Where CodeCloom is today

CodeCloom is a concept. Walkthroughs cannot be created or shared yet.

  1. Now

    Concept

  2. Not started

    Anchoring research

  3. Not started

    Editor

  4. Not started

    Sharing

Questions

Do tours break when code changes?

Keeping steps attached to moving code is the central problem the concept has to solve.

Can I sign up?

Not yet. There is no account system.