Naming and Function Refactor Workshop

Retrieval Prompts

1. State the test for whether a name reveals intent.
2. State the stepdown rule in one sentence.
3. List three kinds of comments that usually fail to earn their place.
4. State the "one thing" rule without mentioning a line-count limit.
5. Name at least three naming anti-patterns (e.g., data, info, manager, Hungarian-style prefix, type-in-name).

Compare and Distinguish

Separate these pairs clearly:

• name reveals intent vs name describes implementation
• comment that earns its place vs comment that masks a bad name
• Extract Function (improves readability) vs Extract Function (hides complexity behind helper)
• short name in small scope vs short name in large scope
• "do one thing" vs "line count below N"

Common Mistake Check

For each snippet or claim, identify the naming or decomposition error:

1. fun handle(x: List<Any>): List<Any>
2. // sorts customers by name above a method that sorts by creation date.
3. A 20-line method extracted as step1, step2, step3, each called once.
4. A boolean parameter named flag passed to process(data, flag).
5. A class named UserDataManager with methods getUserList(), processUserData(), handleUserInfo().

Mini Application

Three tasks, all required:

Task A: Rename log

Pick 10 names from a real codebase (yours or any open-source file). For each:

1. Write the current name.
2. Write the one-sentence purpose you needed to read the body to discover.
3. Write the new name that would have told you that sentence directly.
4. Confirm the rename does not collide with an existing identifier.

Task B: Stepdown rewrite

Take any function over 40 lines. Do all of:

1. Label each line with the abstraction level: L0 = caller intent, L1 = details.
2. For every run of three or more L1 lines, extract into a function directly below the caller.
3. Name each extracted function so that the top-level function reads as a plan.
4. Delete any comment the rename or extraction has made redundant.

Task C: Comment audit

Take any file with at least 10 comments. Do all of:

1. Classify each comment: intent, warning, contract, redundant, misleading, commented-out.
2. Delete every commented-out after confirming git history preserves it.
3. Rewrite or delete every misleading.
4. For every redundant, attempt a rename or extract that removes the need for the comment.

Evidence Check

This page is complete only if you have produced:

• at least 10 concrete renames with justification
• one function that reads as a plan after stepdown
• a smaller number of comments than you started with, with the remaining ones categorized as intent, warning, or contract