A table of contents method is a high-level method whose named calls summarize the sequence of operations performed by its implementation. It lets readers grasp a method’s intent at a glance without reconstructing every low-level step. section 2.0 section 2.6
A readable sequence
A user-creation method can read like a compact outline: validateMandatoryField(lastName, "Last name"); validateBirthDate(birthDate); validateEmail(email); saveUser(firstName, lastName, email, birthDate, city); Each call names a recognizable operation while preserving the overall order. section 2.0
Build the outline from meaningful chunks. Extract lower-level actions, group related actions into scenes, and let the top-level method tell the story through scene-level calls. Do not extract methods merely to satisfy a prescribed level: extraction should improve readability, express a cohesive concept, maintain a uniform abstraction level, or reveal hidden intent. section 2.5 section 2.5
Extract a method only when it earns its place. Do not extract a method only to satisfy a narrative level. Narrative levels describe useful structure; they are not a quota system. If a caller is already short, readable, and at one clear level of abstraction, keep the story there. Extract a method when **any** of these holds: 1. The caller would exceed its chunk budget without the extraction. 2. The group names a cohesive business concept that the individual names cannot convey alone. 3. The extraction keeps the caller at a uniform level of abstraction. 4. The expression is complex, repeated, or hides intent that a name would reveal. Hard blockers (if any, DO NOT extract): 1. Caller is already within budget and readable. 2. Extraction does not make the caller easier to read. 3. The extracted body contains only one simple chunk. 4. The extracted method merely groups already clear calls and adds no domain concept.
Use the extraction criteria to decide whether a proposed helper genuinely improves the table-of-contents structure. section 2.5
Scene: - Up to 6 chunks - Focuses on one recognizable step of the story. - Composes Actions plus simple supporting logic: 1–2 conditionals, 1 loop, or error handling. A Scene must call at least one Action. - Downgrade rule: If a method that would be a Scene calls no Action — only direct inline logic — demote it to an Action.
Use scene boundaries to keep grouped calls focused on one recognizable step while retaining at least one action-level operation. section 2.5
