Write code your future self will understand

We’ve all been there—staring at a piece of code that “works,” but feels like a ticking time bomb. In this hands-on session, we’ll start with a messy, hard-to-maintain snippet of real-world code and walk through the process of transforming it step by step.

First, we’ll apply clean code principles to bring structure and readability. But we won’t stop there. You’ll learn how to go beyond surface-level improvements by introducing strategic patterns from Domain-Driven Design (DDD) that give your code meaning, boundaries, and a strong backbone.

This talk isn’t about theory—it’s a guided refactor that turns obscure code into clear code. You’ll leave with practical techniques to improve existing code and design future features with confidence and purpose.

Transcript

1. WRITE CODE… …THAT YOUR FUTURE SELF WILL UNDERSTAND
2. SILAS JOISTEN LEAD ENGINEER & TRAINER
3. EVER LOOKED AT SOME OLD CODE AND THOUGHT… … WHO THE 🤬 WROTE THIS?
4. 🕵️ SO YOU START INVESTIGATING… 1 git blame -L 42,42 src/Service/ExportService.php
5. WHY CODE BECOMES HARD TO UNDERSTAND
6. 🕵️‍♂️ Cryptic naming 🧙 Clever tricks instead of clear logic 🧩 Over-abstraction 🍝 Mixing business logic, DB calls, and view rendering ❓ Lack of comments, weird edge cases
7. 1 // ... 2 class PriceHandler 3 { 4 private $r, $s; 5 6 public function __construct($r, $s) 7 { 8 $this->r = $r; 9 $this->s = $s; 10 } 11 12 public function handle($d) 13 { 14 $u = $this->r->get($d['i']); 15 if (!$u['p']) { 16 $u['v'] = $u['v'] * 1.19; 17 $this->s->val($u); 18 } 19 return $u; 20 } 21 }
8. CAN WE FIX IT WITH CLEAN CODE? 🧼
9. STEP 1 WRITE TESTS
10. // ... final class PriceHandlerTest extends TestCase { #[Test] public function aPromotionalSubscriptionSkipsVat(): void { $repository = self::createMock(SubscriptionRepository::class); $formatter = self::createMock(PricingFormatterService::class); $repository->method('get')->willReturn(['p' => true, 'v' => 99]); $formatter->expects($this->once())->method('val'); $subscription = (new PriceHandler($repository, $formatter))->handle(['i' => 5]); self::assertSame('0,99€', $subscription['v']); self::assertTrue($subscription['p']); } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
11. STEP 2 USE NATIVE LANGUAGE FEATURES
12. // ... final readonly class PriceHandler { public function __construct( private SubscriptionRepository $r, private PricingFormatterService $s ) { } public function handle(int $d): array { $u = $this->r->get($d); if (!$u['p']) { $u['v'] = $u['v'] * 1.19; $this->s->val($u); } return $u; } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
13. STEP 3 IMPROVE NAMING
14. // ... final readonly class PriceHandler { public function __construct( private SubscriptionRepository $subscriptionRepository, private PricingFormatterService $pricingFormatter ) { } public function applyVat(int $subscriptionId): array { $subscription = $this->subscriptionRepository->get($subscriptionId); if (!$subscription['isPromotion']) { $subscription['price'] = $subscription['price'] * 1.19; $this->pricingFormatter->format($subscription); } return $subscription; } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
15. STEP 4 ADD TYPE ANNOTATIONS AND COMMENTS
16. // ... final readonly class PriceHandler { public function __construct( private SubscriptionRepository $subscriptionRepository, private PricingFormatterService $pricingFormatter, ) { } /** * Germany's VAT for our Subscriptions is 19% * Subscriptions that are promotions do not have VAT applied! * * @return array{isPromotion: bool, price: string} */ public function applyVat(int $subscriptionId): array { /** @var array{isPromotion: bool, price: string} $subscription */ $subscription = $this->subscriptionRepository->get($subscriptionId); if (!$subscription['isPromotion']) { $subscription['price'] = $subscription['price'] * 1.19; $this->pricingFormatter->format($subscription); } return $subscription; } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
17. THIS STILL DOESN’T FEEL RIGHT 😩
18. LET’S TALK ABOUT THE DOMAIN ❓ What is a Subscription in my domain ❓ What is a Price in my domain ❓ What does it mean to be a promotional subscription ❓ What does it mean to change a subscription’s price
19. THE ARTIFACTS OF DDD WORD DESCRIPTION Entity Unique object with an identity Value Object Data with no identity, defined by attributes Aggregate Group of related entities treated as a single unit Relationship How content entities connect Bounded Context Defines the limits of a domain
20. 1 // ... 2 final readonly class PriceHandler 3 { 4 public function __construct( 5 private SubscriptionRepository $subscriptionRepository, 6 private PricingFormatterService $pricingFormatter, 7 ) { 8 } 9 10 /** 11 * Germany's VAT for our Subscriptions is 19% 12 * Subscriptions that are promotions do not have VAT applied! 13 * 14 * @return array{isPromotion: bool, price: string} 15 */ 16 public function applyVat(int $subscriptionId): array 17 { 18 /** @var array{isPromotion: bool, price: string} $subscription */ 19 $subscription = $this->subscriptionRepository->get($subscriptionId); 20 21 if (!$subscription['isPromotion']) { 22 $subscription['price'] = $subscription['price'] * 1.19; 23 $this->pricingFormatter->format($subscription); 24 } 25 26 return $subscription; 27 } 28 }
21. VALUE OBJECTS Requires webmozart/assert library. Assert::xxx throws an \InvalidArgumentException if the condition is not met. 1 final readonly class SubscriptionId 2 { 3 public function __construct( 4 public int $value, 5 ) { 6 Assert::positiveInteger($id, 'Subscription ID must be a positive integer'); 7 } 8 }
22. VALUE OBJECTS 1 final readonly class Price 2 { 3 public function __construct( 4 public int $value, 5 public string $currency = '€', 6 ) { 7 Assert::positiveInteger($value); 8 Assert::stringNotEmpty($currency); 9 Assert::notWhitespaceOnly($currency); 10 } 11 12 public function toString(): string 13 { 14 return sprintf('%01.2f%s', $this->value / 100.0, $this->currency); 15 } 16 }
23. ENTITIES 1 final readonly class Subscription 2 { 3 public function __construct( 4 public SubscriptionId $id, 5 public Price $price, 6 private bool $isPromotion = false, 7 ) { 8 } 9 10 public function withPrice(Price $price): self 11 { 12 return new self($this->id, $this->name, $price, $this->isPromotion); 13 } 14 }
24. SERVICES 1 final readonly class VatHandler 2 { 3 /** 4 * Germany's VAT for our Subscriptions is 19% 5 * Subscriptions that are promotions do not have VAT applied! 6 */ 7 public function forGermany(Subscription $subscription): Subscription 8 { 9 if ($subscription->isPromotion) { 10 return $subscription; 11 } 12 13 return $subscription->withPrice(new Price($subscription->price * 1.19)); 14 } 15 }
25. CONTROLLERS 1 final class SubscriptionController extends AbstractController 2 { 3 #[Route('/subscriptions/{id}/price')] 4 public function index(int $id, VatHandler $vat, SubscriptionRepository $subscriptions): Response 5 { 6 $subscription = $vat->forGermany($subscriptions->byId(new SubscriptionId($id))); 7 8 // do other subscription operations 9 10 return $this->json(['price' => $subscription->price->toString()]); 11 } 12 }
26. TOOLS THAT HELP PHPSTAN – STATIC ANALYSIS RECTOR – AUTOMATED REFACTORING SYMFONY INSIGHT – PROJECT HEALTH PHP-CS FIXER – CODE STYLE
27. KEY TAKEAWAYS Code is communication — write it for other humans Your future self is just another dev with no context Maintainable code is an act of empathy 🫶
28. THANK YOU! ❤️ ANY QUESTIONS?
29. LET’S CONNECT @silasjoisten @JoistenSilas Silas Joisten