Before we Begin

Think about a piece of code you:

  1. Don't understand
  2. Want to change

Write it down.

We're going to work on that later!

Work Code

OSS Project

Scratch Refactoring to Understand: Unearthing your Domain


Scratch Refactoring to Understand: Unearthing your Domain

  • Web Developer
  • Contractor/Architect/Consultant
  • Specialise in Legacy Web Apps
  • Insanely good at Mario Kart
  • DDD IE Organiser
  • PHP Dublin Organiser


Barry O Sullivan

About me

  1. The difficulties of existing code
  2. Why it's difficult
  3. Scratch Refactoring
  4. Techniques
  5. Scratch Refactoring Session

Session Structure

Existing Code

How we want to write code

  1. Plan desired change to system
  2. Estimate it
  3. Look through the codebase
  4. Figure out where we need to change
  5. Make the change
  6. Verify it

How we actually write code

  1. Plan desired change to system
  2. Estimate it
  3. Look through the codebase
  4. Realise we don't understand it at all
  5.   ** PANIC **
  6. Guess at where we need to change
  7. Hack it in
  8. Attempt to verify it (happy path only)
  9. Fix inevitable bugs

Most Existing Code is Hard to Understand

System Understanding











Scratch Refactoring

Refactor a piece of code without worrying about it running.


The goal is to explore the code and gain understanding, not to write working code.

Scratch Refactoring


Trash it

Where it's from

Different Perspectives

DDD Perspectives







- See which concepts work and which don't

- Spotted what's muddying the water

- An idea on how to isolate concepts

- Able to plan an iterative step forward

The End Results

Real World Example

public function save($class_name, $post, $id)
$rc = new \ReflectionClass("\\Elections\\". $class_name . "Director");
$director = $rc->newInstanceArgs(array($id));










  • Rename vars/methods/classes
  • Private method extraction
  • Extract Conditionals
  • Extract Factories
  • Extract Infrastructure
    • DB / API Calls / Filesystem
  • Extract Input
    • HTTP / Message / Console

Tactical Techniques

  • Extract ValueObjects
  • Extract Entities
  • Pretend a Class Exists
  • Create Class inline
  • Inline Abstractions
    • Abstract class / Method calls

Useful Perspectives

Why are you changing this code?

Domain Language / Concepts

What is Input & Output





Application / Domain

  • Lean on auto refactoring tools
  • Describe the behaviour not the implementation
  • Put like with like: Private vars, methods
  • Focus on the code that matters, isolate and ignore the rest
  • Do it in pairs/mobs
  • Take notes of discoveries and concepts
  • Scrap it all and start again, see where you end up!

+Scratch Refactoring Tips+

The Hands-on Session

Scratch Refactoring 

  1. Find a messy piece of code and scratch refactor it
  2. Choose a technique, try it out for 30mins
  3. Reset, choose another and try that for 30mins
  4. Review: What's signal and what's noise
  • Do it alone or in pairs
  • If you don't have a laptop/code, pair up with someone
  • Go mad, try out ideas and see where you get!
  • No wrong answers, you can always start again

Increase Understanding

Increase Developer Knowledge by

Finding Consistent Patterns and

Diagnosing Accidental Complication

Through Scratch Refactoring



DDD EU 2020 - Scratching Refactoring: Unearthing your domain

By Barry O' Sullivan

DDD EU 2020 - Scratching Refactoring: Unearthing your domain

How do you deal with code that you don't understand? Not all code is well structured and easy to digest, most code isn't. It is our job to take this code and make changes without introducing bugs, and this is by no means an easy task. To make things harder, we actually want to improve this messy code, to refactor it into something more manageable. Well, the good news is that this is possible, you just need a foothold of understanding in that code, and Scratch Refactoring is that foothold. Scratch Refactoring is a technique that help us navigate and understand messy code, it's about trying out changes to code without committing to them, changes that could otherwise be expensive. It allows us to explore code and domain models without breaking the underlying code. The goal isn't to rewrite, it's to explore mental models of the underlying domain. This is very powerful when working with difficult code. This workshop will focus on Scratch Refactoring and how to apply it. We'll discuss the concept, look at techniques we can use to accelerate the process, different strategies for gaining clarity, and how tactical DDD patterns can be applied to explore potential domain concepts. Then we will apply these ideas to code we've brought in ourselves. That's right, we'll try out Scratch Refactoring on our own problem space. This is a great way to try out the technique in a domain or codebase

  • 1,208