[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":84,"_71":85,"_35":86},"articles",{"_11":12,"_13":14,"_15":16,"_17":16,"_18":19,"_20":21,"_22":23,"_24":23,"_25":16,"_26":27},"content",[30],"pageable",{"_28":21,"_29":19},"totalElements",1,"totalPages","size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_31":32,"_33":34,"_35":36,"_37":38,"_11":39,"_40":-5,"_41":23,"_42":27,"_43":44,"_45":46,"_47":48,"_49":50,"_51":32,"_52":32,"_53":54,"_55":56,"_57":58,"_59":32,"_60":16,"_61":62,"_63":64,"_65":66,"_67":68,"_69":70},"id",20,"title","Working with Legacy Code","slug","clean-code-part-19-legacy-code","excerpt","Read and understand unfamiliar code: identify seams for testing, sketch refactoring, and safely modify legacy systems without breaking them.","# Advanced Clean Code Patterns Part 19: Understanding Legacy Code\n\nWorking with legacy code is an essential skill. Most developers spend more time maintaining existing code than writing new code. This article covers techniques for understanding, documenting, and safely modifying code you didn't write.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| Definition | Code without tests, or code you're afraid to change |\n| Key Challenge | Understanding before modifying |\n| Primary Tool | Characterization tests |\n| Mindset | Surgical precision, not rewrites |\n\n---\n\n## 🎯 What You'll Learn\n\n- **Reading strategies** for understanding unfamiliar code\n- **Identifying seams** for testing and modification\n- **Sketch refactoring** for exploration\n- **Documentation techniques** for knowledge capture\n- **Safe modification** strategies\n\n---\n\n## Production Story: The Scary Codebase\n\nA developer inherited a 50,000-line payment processing system:\n\n```java\n// ❌ Legacy nightmare - no tests, no docs\npublic class PaymentProcessor {\n public Object process(Map params) {\n Object result = null;\n try {\n // 500 lines of nested conditionals\n if (params.get(\"type\") != null) {\n if (params.get(\"type\").equals(\"CC\")) {\n // 200 lines\n } else if (params.get(\"type\").equals(\"ACH\")) {\n // 150 lines\n }\n // ... more branches\n }\n // Side effects everywhere\n GlobalState.lastPayment = params;\n EmailSender.send(params.get(\"email\"), \"processed\");\n } catch (Exception e) {\n // Swallowed exception\n }\n return result;\n }\n}\n```\n\n**First instinct:** Rewrite everything\n**Reality:** Rewrite would take 6 months and introduce new bugs\n\n**The fix:** Incremental improvement with characterization tests:\n\n1. Write tests that document current behavior\n2. Add seams for testability\n3. Make small, safe changes\n4. Repeat\n\n---\n\n## Mental Model: Legacy Code Workflow\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│ LEGACY CODE IMPROVEMENT CYCLE │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ 1. UNDERSTAND │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ • Read the code (don't judge yet) │ │\n│ │ • Find entry points │ │\n│ │ • Trace execution paths │ │\n│ │ • Document discoveries │ │\n│ └────────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ 2. CHARACTERIZE │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ • Write tests for CURRENT behavior │ │\n│ │ • Tests are documentation │ │\n│ │ • Tests protect against regression │ │\n│ └────────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ 3. IDENTIFY SEAMS │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ • Find places to insert test doubles │ │\n│ │ • Constructor parameters, method overrides │ │\n│ │ • Static methods are seam killers │ │\n│ └────────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ 4. MAKE CHANGES │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ • Small, incremental changes │ │\n│ │ • Run tests after each change │ │\n│ │ • Commit frequently │ │\n│ └────────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ 5. REFACTOR (if time permits) │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ • Clean up what you touched │ │\n│ │ • Leave code better than you found it │ │\n│ │ • Don't gold-plate │ │\n│ └────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🔬 Deep Dive\n\n### Technique 1: Reading Strategies\n\n```java\n// Start with entry points - controllers, main methods, scheduled tasks\n\n// 1. Find the entry point\n@RestController\npublic class OrderController {\n @PostMapping(\"/orders\")\n public Order createOrder(@RequestBody OrderRequest request) {\n return orderService.create(request); // Follow this\n }\n}\n\n// 2. Trace the call chain - take notes\n/*\n * Call Chain Notes:\n * OrderController.createOrder()\n * → OrderService.create()\n * → OrderValidator.validate() // Throws ValidationException\n * → InventoryService.reserve() // Side effect: reduces stock\n * → PaymentService.charge() // Side effect: charges card\n * → OrderRepository.save()\n * → EmailService.send() // Side effect: sends email\n *\n * Questions:\n * - What happens if payment fails after inventory reserved?\n * - Is there transaction rollback?\n * - What triggers the email?\n */\n\n// 3. Look for patterns, not details\n// Ask: What's the INTENT, not what does each line do?\n\n// 4. Identify dependencies\npublic class OrderService {\n private final OrderRepository orderRepo; // Data access\n private final InventoryService inventory; // External system?\n private final PaymentService payment; // External system!\n private final EmailService email; // Side effect\n // These are the things that make testing hard\n}\n```\n\n**Reading tips:**\n- Read with a specific question in mind\n- Use IDE \"Find Usages\" liberally\n- Draw diagrams (sequence, class)\n- Take notes as you go\n\n---\n\n### Technique 2: Scratch Refactoring\n\n```java\n// Scratch refactoring: refactor to understand, then DISCARD changes\n\n// Original - hard to understand\npublic void processPayment(Map data) {\n String type = (String) data.get(\"type\");\n if (type != null && type.equals(\"CC\")) {\n String num = (String) data.get(\"number\");\n String exp = (String) data.get(\"exp\");\n String cvv = (String) data.get(\"cvv\");\n if (num != null && num.length() == 16) {\n if (exp != null && exp.matches(\"\\\\d{2}/\\\\d{2}\")) {\n if (cvv != null && cvv.length() == 3) {\n // 100 more lines...\n }\n }\n }\n }\n}\n\n// Scratch refactor - JUST TO UNDERSTAND\n// Then git checkout to discard\npublic void processPayment(PaymentData data) {\n if (!data.isCreditCard()) return;\n\n CreditCardDetails card = data.getCreditCard();\n if (!card.isValid()) return;\n\n // Ah! Now I understand:\n // 1. Only handles credit cards\n // 2. Validates card format\n // 3. Then processes...\n}\n\n// Key: Discard changes after understanding!\n// You learned, but didn't risk breaking anything\n```\n\n---\n\n### Technique 3: Identifying Code Structure\n\n```java\n// Look for these common patterns in legacy code\n\n// 1. GOD CLASS - does everything\npublic class OrderManager {\n public void createOrder() { /* 200 lines */ }\n public void updateOrder() { /* 150 lines */ }\n public void deleteOrder() { /* 100 lines */ }\n public void sendEmail() { /* 50 lines */ }\n public void generateReport() { /* 300 lines */ }\n public void importFromCsv() { /* 200 lines */ }\n // ... 5000 more lines\n}\n\n// 2. FEATURE ENVY - method uses another class's data\npublic BigDecimal calculateShipping(Order order) {\n // Uses Order's internals extensively\n BigDecimal weight = order.getItems().stream()\n .map(i -> i.getProduct().getWeight())\n .reduce(BigDecimal.ZERO, BigDecimal::add);\n String zone = order.getAddress().getShippingZone();\n // This probably belongs IN Order class\n}\n\n// 3. SHOTGUN SURGERY - change requires edits everywhere\n// Adding new payment type requires changes in:\n// - PaymentProcessor.java\n// - PaymentValidator.java\n// - PaymentReporter.java\n// - PaymentEmails.java\n// - PaymentMetrics.java\n// ... 10 more files\n\n// 4. HIDDEN DEPENDENCIES\npublic class ReportGenerator {\n public void generate() {\n // Hidden dependency on global state\n Config config = GlobalConfig.getInstance(); // Where's this from?\n Database db = DatabasePool.getConnection(); // Static access\n // Can't test without real database!\n }\n}\n```\n\n---\n\n### Technique 4: Finding Seams\n\n```java\n// SEAM: A place where you can alter behavior without editing source\n\n// 1. OBJECT SEAM - Override method or inject dependency\npublic class PaymentService {\n private final PaymentGateway gateway;\n\n // Constructor injection = seam!\n public PaymentService(PaymentGateway gateway) {\n this.gateway = gateway; // Can inject mock\n }\n\n public void process(Payment payment) {\n gateway.charge(payment); // Can mock this\n }\n}\n\n// 2. SUBCLASS SEAM - Override protected method\npublic class LegacyProcessor {\n public void process() {\n validate();\n Data data = fetchData(); // Can't mock - but can override!\n transform(data);\n save();\n }\n\n protected Data fetchData() {\n return database.query(\"...\"); // Override this in test subclass\n }\n}\n\n// Test with override\npublic class TestableProcessor extends LegacyProcessor {\n @Override\n protected Data fetchData() {\n return new Data(\"test data\"); // No database needed!\n }\n}\n\n// 3. PREPROCESSING SEAM - Extract and override\n// Before: hardcoded dependency\npublic void sendNotification() {\n EmailSender sender = new EmailSender(); // Can't mock!\n sender.send(message);\n}\n\n// After: extracted creation\npublic void sendNotification() {\n EmailSender sender = createEmailSender(); // Seam!\n sender.send(message);\n}\n\nprotected EmailSender createEmailSender() {\n return new EmailSender();\n}\n```\n\n---\n\n### Technique 5: Safe Modification Techniques\n\n```java\n// SPROUT METHOD - Add new code in new method\n\n// Original - don't touch!\npublic void processOrder(Order order) {\n // 100 lines of existing code...\n validate(order);\n calculateTax(order);\n // Need to add discount calculation HERE\n saveOrder(order);\n}\n\n// Sprout new method\npublic void processOrder(Order order) {\n validate(order);\n calculateTax(order);\n applyDiscounts(order); // Sprouted method\n saveOrder(order);\n}\n\n// New code in isolated, testable method\nprivate void applyDiscounts(Order order) {\n // New code here - fully tested\n if (order.getCustomer().isVip()) {\n order.setDiscount(calculateVipDiscount(order));\n }\n}\n\n// WRAP METHOD - Wrap existing method\n// Original\npublic void pay(Payment payment) {\n // Legacy code\n}\n\n// Wrapped - add behavior before/after\npublic void pay(Payment payment) {\n logPaymentAttempt(payment); // New: before\n payOriginal(payment); // Renamed original\n recordMetrics(payment); // New: after\n}\n\nprivate void payOriginal(Payment payment) {\n // Original code, untouched\n}\n\n// SPROUT CLASS - New functionality in new class\n// Don't add to 5000-line class, create new one\npublic class OrderDiscountCalculator {\n private final Order order;\n\n public BigDecimal calculate() {\n // All new code, fully tested\n }\n}\n\n// Then call from legacy code\npublic void processOrder(Order order) {\n // existing code...\n BigDecimal discount = new OrderDiscountCalculator(order).calculate();\n // existing code...\n}\n```\n\n---\n\n### Technique 6: Documentation as You Go\n\n```java\n// Document your discoveries for the next person (including future you)\n\n/**\n * Payment processing for credit card transactions.\n *\n * DISCOVERED BEHAVIOR (2024-01):\n * - Only processes amounts > $0.50 (minimum charge)\n * - Retries up to 3 times on network failure\n * - Side effect: logs to PaymentAudit table\n * - Side effect: sends email on failure\n *\n * KNOWN ISSUES:\n * - #1234: Race condition when concurrent charges for same customer\n * - Doesn't handle currency conversion\n *\n * DEPENDENCIES:\n * - PaymentGateway: Stripe API (production), Mock (test)\n * - AuditLog: Database table (payment_audit)\n * - EmailService: SendGrid\n *\n * TEST COVERAGE:\n * - CharacterizationTests.testCreditCardPayment()\n * - Unit tests don't exist (legacy)\n *\n * REFACTORING IDEAS (don't do unless needed):\n * - Extract validation to separate class\n * - Replace Map with typed PaymentRequest\n */\npublic class PaymentProcessor {\n // ...\n}\n\n// Inline comments for non-obvious behavior\npublic void process(Payment payment) {\n // IMPORTANT: Must validate BEFORE checking balance\n // (see incident #789 - validation changed balance)\n validate(payment);\n\n // NOTE: This sleep is intentional - rate limiting for API\n Thread.sleep(100);\n\n // WARNING: Gateway.charge() is NOT idempotent\n // Always check for duplicate before calling\n if (!isDuplicate(payment)) {\n gateway.charge(payment);\n }\n}\n```\n\n---\n\n### Technique 7: Incremental Improvement\n\n```java\n// Don't try to fix everything at once\n\n// Week 1: Add characterization tests\n@Test\nvoid processPayment_creditCard_chargesCorrectAmount() {\n // Test documents current behavior\n processor.process(createCreditCardPayment(100.00));\n verify(gateway).charge(100.00);\n}\n\n// Week 2: Extract one piece to testable class\npublic class PaymentValidator {\n public ValidationResult validate(Payment payment) {\n // Extracted from monster method\n // Now fully unit tested\n }\n}\n\n// Week 3: Add one new feature with tests\npublic class FraudChecker {\n // New code, test-first\n public FraudRisk assess(Payment payment) {\n // Fully tested new code\n }\n}\n\n// Week 4: Integrate new code\npublic void process(Payment payment) {\n // Existing code...\n FraudRisk risk = fraudChecker.assess(payment); // New\n if (risk.isHigh()) {\n flagForReview(payment);\n }\n // Existing code...\n}\n\n// Result: Codebase gradually improves without breaking changes\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Trying to Understand Everything\n\n```text\n❌ \"I need to understand the entire codebase before changing anything\"\n\n✅ Focus on the code path you need to change\n - Entry point to your change\n - Code that calls your change\n - Code your change calls\n```\n\n### Mistake 2: Big Bang Rewrites\n\n```text\n❌ \"This code is terrible, let's rewrite it from scratch\"\n - Rewrites take longer than expected\n - Original behavior is lost\n - New bugs replace old bugs\n\n✅ Incremental improvement\n - Add tests first\n - Small changes\n - Refactor as you go\n```\n\n---\n\n## 🐛 Debug This: The Flaky Test\n\nA developer added a characterization test for legacy code, but it fails intermittently. Sometimes it passes, sometimes it doesn't. \"I don't understand - I'm testing the exact same code path!\"\n\n```java\n// Legacy code being tested\npublic class OrderProcessor {\n private static List processedOrders = new ArrayList<>();\n\n public OrderResult process(Order order) {\n // Validate\n if (order.getTotal().compareTo(BigDecimal.ZERO) <= 0) {\n return OrderResult.invalid(\"Amount must be positive\");\n }\n\n // Check for duplicate\n if (processedOrders.contains(order.getId())) {\n return OrderResult.duplicate();\n }\n\n // Process\n processedOrders.add(order.getId());\n\n // More processing...\n PaymentGateway.charge(order.getCustomerId(), order.getTotal());\n\n return OrderResult.success();\n }\n}\n\n// The flaky test\npublic class OrderProcessorTest {\n\n @Test\n void testProcessOrder_validOrder_succeeds() {\n OrderProcessor processor = new OrderProcessor();\n Order order = new Order(\"ORD-001\", new BigDecimal(\"99.99\"), \"CUST-1\");\n\n OrderResult result = processor.process(order);\n\n assertEquals(OrderResult.success(), result);\n }\n\n @Test\n void testProcessOrder_duplicateOrder_returnsDuplicate() {\n OrderProcessor processor = new OrderProcessor();\n Order order = new Order(\"ORD-002\", new BigDecimal(\"50.00\"), \"CUST-2\");\n\n processor.process(order); // First call\n OrderResult result = processor.process(order); // Second call\n\n assertEquals(OrderResult.duplicate(), result);\n }\n}\n```\n\n**Tests pass individually but fail when run together. What's wrong?**\n\n---\n\n**✅ Solution:**\n\nTwo common legacy code traps:\n\n**Problem 1: Static shared state**\n\n```java\nprivate static List processedOrders = new ArrayList<>();\n```\n\nThe `processedOrders` list is **static** - shared across all instances and all tests! When tests run together, order IDs from one test \"leak\" into another.\n\n**Problem 2: Hidden external dependency**\n\n```java\nPaymentGateway.charge(order.getCustomerId(), order.getTotal());\n```\n\nStatic method call to `PaymentGateway` - if this makes real API calls or has its own static state, tests become unpredictable.\n\n**Correct approach - identify seams and isolate:**\n\n```java\npublic class OrderProcessorTest {\n\n @BeforeEach\n void setUp() {\n // Clear the static state (temporary fix)\n // Better: refactor to inject dependency\n clearProcessedOrders();\n }\n\n private void clearProcessedOrders() {\n try {\n Field field = OrderProcessor.class.getDeclaredField(\"processedOrders\");\n field.setAccessible(true);\n ((List) field.get(null)).clear();\n } catch (Exception e) {\n throw new RuntimeException(\"Failed to clear state\", e);\n }\n }\n\n @Test\n void testProcessOrder_validOrder_succeeds() {\n // Use subclass seam to override PaymentGateway call\n OrderProcessor processor = new TestableOrderProcessor();\n Order order = new Order(\"ORD-001\", new BigDecimal(\"99.99\"), \"CUST-1\");\n\n OrderResult result = processor.process(order);\n\n assertEquals(OrderResult.success(), result);\n }\n}\n\n// Subclass seam to isolate external dependency\nclass TestableOrderProcessor extends OrderProcessor {\n @Override\n protected void chargePayment(String customerId, BigDecimal amount) {\n // No-op in tests - or record for verification\n }\n}\n```\n\n**The lesson:** Legacy code often has hidden static state and static method dependencies. Always check for these when tests behave inconsistently!\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Identify Seams\n⭐ Difficulty: Easy | ⏱️ Time: 10 minutes\n\n**Task:** Identify all seams in this legacy class where you could inject test doubles.\n\n```java\npublic class ReportGenerator {\n private ReportRepository repository = new ReportRepository();\n\n public Report generate(String reportId) {\n ReportConfig config = ConfigManager.getConfig();\n\n Data data = fetchData(reportId);\n\n String formatted = Formatter.format(data, config.getFormat());\n\n if (config.shouldEmail()) {\n EmailService.send(config.getRecipient(), formatted);\n }\n\n return repository.save(new Report(reportId, formatted));\n }\n\n protected Data fetchData(String reportId) {\n return DatabaseConnection.getInstance().query(\"SELECT * FROM data WHERE id = ?\", reportId);\n }\n}\n```\n\n**List all seams and classify them (Object/Subclass/Preprocessing).**\n\n**✅ Solution:**\n\n| Location | Type | How to Use |\n|----------|------|------------|\n| `repository` field | Object Seam | Change field access to constructor injection, inject mock |\n| `ConfigManager.getConfig()` | Preprocessing Seam | Extract to `protected getConfig()` method, override in test |\n| `fetchData()` | Subclass Seam | Already protected! Override in test subclass |\n| `Formatter.format()` | No seam (static) | Need to wrap in instance method first |\n| `EmailService.send()` | Preprocessing Seam | Extract to `protected sendEmail()`, override |\n| `DatabaseConnection.getInstance()` | No seam (singleton) | Already in `fetchData()` - use subclass seam |\n\n**Testable refactor:**\n\n```java\npublic class ReportGenerator {\n private final ReportRepository repository;\n\n public ReportGenerator(ReportRepository repository) { // Object seam\n this.repository = repository;\n }\n\n protected ReportConfig getConfig() { // Preprocessing seam\n return ConfigManager.getConfig();\n }\n\n protected void sendEmail(String recipient, String content) { // Preprocessing seam\n EmailService.send(recipient, content);\n }\n\n // fetchData() already a subclass seam\n}\n```\n\n---\n\n### Exercise 2: Scratch Refactoring\n⭐⭐ Difficulty: Medium | ⏱️ Time: 20 minutes\n\n**Task:** Use scratch refactoring to understand this legacy method. Document what you discover, then discard your changes.\n\n```java\npublic Object processTransaction(Map params) {\n Object result = null;\n int status = 0;\n String type = (String) params.get(\"type\");\n if (type != null) {\n if (type.equals(\"CREDIT\") || type.equals(\"DEBIT\")) {\n BigDecimal amt = (BigDecimal) params.get(\"amount\");\n if (amt != null && amt.compareTo(BigDecimal.ZERO) > 0) {\n String acct = (String) params.get(\"account\");\n if (acct != null && acct.length() == 10) {\n if (type.equals(\"CREDIT\")) {\n status = db.execute(\"UPDATE accounts SET balance = balance + ? WHERE id = ?\", amt, acct);\n } else {\n BigDecimal bal = (BigDecimal) db.query(\"SELECT balance FROM accounts WHERE id = ?\", acct);\n if (bal != null && bal.compareTo(amt) >= 0) {\n status = db.execute(\"UPDATE accounts SET balance = balance - ? WHERE id = ?\", amt, acct);\n } else {\n status = -2;\n }\n }\n } else {\n status = -3;\n }\n } else {\n status = -4;\n }\n } else {\n status = -5;\n }\n } else {\n status = -1;\n }\n if (status > 0) result = \"OK\";\n else if (status == 0) result = \"NOOP\";\n else result = \"ERROR:\" + status;\n return result;\n}\n```\n\n**Document: What does this code do? What are the error codes?**\n\n**✅ Solution:**\n\n**Understanding after scratch refactoring:**\n\n```java\n// Scratch refactor for understanding (DISCARD AFTER!)\npublic TransactionResult processTransaction(TransactionRequest request) {\n // 1. Validate transaction type (must be CREDIT or DEBIT)\n if (!request.isValidType()) {\n return TransactionResult.error(INVALID_TYPE); // status -5\n }\n\n // 2. Validate amount (must be positive)\n if (!request.hasValidAmount()) {\n return TransactionResult.error(INVALID_AMOUNT); // status -4\n }\n\n // 3. Validate account (must be 10 characters)\n if (!request.hasValidAccount()) {\n return TransactionResult.error(INVALID_ACCOUNT); // status -3\n }\n\n // 4. Process based on type\n if (request.isCredit()) {\n // Credits always succeed (no balance check)\n return credit(request.getAccount(), request.getAmount());\n } else {\n // Debits require sufficient balance\n if (!hasSufficientBalance(request.getAccount(), request.getAmount())) {\n return TransactionResult.error(INSUFFICIENT_FUNDS); // status -2\n }\n return debit(request.getAccount(), request.getAmount());\n }\n}\n```\n\n**Documentation:**\n\n```\nDISCOVERED BEHAVIOR:\n- Processes CREDIT and DEBIT transactions\n- CREDIT: Adds amount to account (no balance check)\n- DEBIT: Subtracts amount (requires sufficient balance)\n\nERROR CODES:\n-1: Missing transaction type\n-2: Insufficient funds (DEBIT only)\n-3: Invalid account number (must be 10 chars)\n-4: Invalid amount (must be > 0)\n-5: Invalid transaction type (must be CREDIT/DEBIT)\n\nRETURN VALUES:\n\"OK\": Transaction successful\n\"NOOP\": No operation performed\n\"ERROR:-X\": Failed with error code X\n\nNOTES:\n- No input type is null - Map returns null for missing keys\n- Account validation is only length check (no existence check!)\n- Race condition: balance check and update not atomic\n```\n\n---\n\n### Exercise 3: Sprout Method Technique\n⭐⭐ Difficulty: Medium | ⏱️ Time: 15 minutes\n\n**Task:** You need to add audit logging to this legacy method. Use the Sprout Method technique to add the feature without modifying the existing logic.\n\n```java\npublic class PaymentService {\n public PaymentResult process(Payment payment) {\n // Validate\n if (payment.getAmount().compareTo(BigDecimal.ZERO) <= 0) {\n return PaymentResult.invalid(\"Amount must be positive\");\n }\n if (payment.getCardNumber() == null || payment.getCardNumber().length() != 16) {\n return PaymentResult.invalid(\"Invalid card number\");\n }\n\n // Process payment\n GatewayResponse response = gateway.charge(payment.getCardNumber(), payment.getAmount());\n\n if (response.isSuccessful()) {\n return PaymentResult.success(response.getTransactionId());\n } else {\n return PaymentResult.failed(response.getErrorMessage());\n }\n }\n}\n```\n\n**Add audit logging for: start, validation result, gateway call, and final result.**\n\n**✅ Solution:**\n\n```java\npublic class PaymentService {\n private final AuditLogger auditLogger;\n\n public PaymentService(PaymentGateway gateway, AuditLogger auditLogger) {\n this.gateway = gateway;\n this.auditLogger = auditLogger;\n }\n\n public PaymentResult process(Payment payment) {\n // SPROUTED: Start audit\n auditPaymentStart(payment);\n\n // Validate - existing code untouched\n if (payment.getAmount().compareTo(BigDecimal.ZERO) <= 0) {\n PaymentResult result = PaymentResult.invalid(\"Amount must be positive\");\n auditPaymentComplete(payment, result); // SPROUTED\n return result;\n }\n if (payment.getCardNumber() == null || payment.getCardNumber().length() != 16) {\n PaymentResult result = PaymentResult.invalid(\"Invalid card number\");\n auditPaymentComplete(payment, result); // SPROUTED\n return result;\n }\n\n // SPROUTED: Audit before gateway call\n auditGatewayCall(payment);\n\n // Process payment - existing code untouched\n GatewayResponse response = gateway.charge(payment.getCardNumber(), payment.getAmount());\n\n PaymentResult result;\n if (response.isSuccessful()) {\n result = PaymentResult.success(response.getTransactionId());\n } else {\n result = PaymentResult.failed(response.getErrorMessage());\n }\n\n // SPROUTED: Final audit\n auditPaymentComplete(payment, result);\n return result;\n }\n\n // Sprouted methods - new, fully tested\n private void auditPaymentStart(Payment payment) {\n auditLogger.log(AuditEvent.builder()\n .type(\"PAYMENT_START\")\n .paymentId(payment.getId())\n .amount(payment.getAmount())\n .maskedCard(maskCard(payment.getCardNumber()))\n .timestamp(Instant.now())\n .build());\n }\n\n private void auditGatewayCall(Payment payment) {\n auditLogger.log(AuditEvent.builder()\n .type(\"GATEWAY_CALL\")\n .paymentId(payment.getId())\n .timestamp(Instant.now())\n .build());\n }\n\n private void auditPaymentComplete(Payment payment, PaymentResult result) {\n auditLogger.log(AuditEvent.builder()\n .type(\"PAYMENT_COMPLETE\")\n .paymentId(payment.getId())\n .status(result.getStatus())\n .message(result.getMessage())\n .timestamp(Instant.now())\n .build());\n }\n\n private String maskCard(String cardNumber) {\n if (cardNumber == null || cardNumber.length() < 4) return \"****\";\n return \"****\" + cardNumber.substring(cardNumber.length() - 4);\n }\n}\n```\n\n---\n\n### Exercise 4: Document Legacy Code\n⭐⭐⭐ Difficulty: Medium-Hard | ⏱️ Time: 20 minutes\n\n**Task:** Write comprehensive documentation for this undocumented legacy class based on code analysis.\n\n```java\npublic class UserSync {\n private final Map lastSync = new ConcurrentHashMap<>();\n private static final long SYNC_INTERVAL = 300000;\n\n public void sync(String userId) {\n Long last = lastSync.get(userId);\n if (last != null && System.currentTimeMillis() - last < SYNC_INTERVAL) {\n return;\n }\n\n User local = localDb.findById(userId);\n User remote = remoteApi.fetchUser(userId);\n\n if (local == null && remote != null) {\n localDb.save(remote);\n } else if (local != null && remote != null) {\n if (remote.getUpdatedAt().isAfter(local.getUpdatedAt())) {\n local.setName(remote.getName());\n local.setEmail(remote.getEmail());\n local.setUpdatedAt(remote.getUpdatedAt());\n localDb.save(local);\n }\n } else if (local != null && remote == null) {\n if (local.getCreatedAt().isBefore(Instant.now().minus(30, ChronoUnit.DAYS))) {\n localDb.delete(local);\n }\n }\n\n lastSync.put(userId, System.currentTimeMillis());\n }\n\n public void syncAll() {\n Set allIds = new HashSet<>();\n allIds.addAll(localDb.findAllIds());\n allIds.addAll(remoteApi.fetchAllIds());\n allIds.forEach(this::sync);\n }\n}\n```\n\n**✅ Solution:**\n\n```java\n/**\n * Synchronizes user data between local database and remote API.\n *\n * BEHAVIOR:\n * - Syncs individual users or all users at once\n * - Rate-limited: skips sync if user was synced within last 5 minutes\n * - Handles three scenarios:\n * 1. Remote only: Creates local copy\n * 2. Both exist: Updates local if remote is newer\n * 3. Local only: Deletes if local record is >30 days old\n *\n * SYNC RULES:\n * - Remote is source of truth for existing users\n * - Old local-only records are cleaned up (>30 days)\n * - Recent local-only records are kept (may be pending upload)\n * - Only name, email, updatedAt are synced (not all fields!)\n *\n * RATE LIMITING:\n * - Uses ConcurrentHashMap for thread safety\n * - 5-minute interval per user (300,000 ms)\n * - Rate limit tracked in memory (lost on restart)\n *\n * DEPENDENCIES:\n * - localDb: Local database repository\n * - remoteApi: Remote API client (may throw on network errors)\n *\n * KNOWN ISSUES:\n * - No error handling for API failures\n * - No retry logic for failed syncs\n * - Memory leak: lastSync map grows unbounded\n * - syncAll() may cause API rate limiting\n * - Not transactional: partial updates possible\n *\n * THREAD SAFETY:\n * - lastSync is thread-safe (ConcurrentHashMap)\n * - sync() method is NOT thread-safe (race conditions)\n * - Multiple threads could sync same user simultaneously\n *\n * CONSTANTS:\n * - SYNC_INTERVAL: 300,000 ms (5 minutes)\n * - Cleanup threshold: 30 days\n *\n * SUGGESTED IMPROVEMENTS:\n * - Add error handling and logging\n * - Implement bounded cache for lastSync\n * - Add synchronization for concurrent access\n * - Make sync interval configurable\n *\n * @see LocalDatabase#findById(String)\n * @see RemoteApi#fetchUser(String)\n */\npublic class UserSync {\n // ... existing code\n}\n```\n\n---\n\n### Exercise 5: Full Legacy Improvement Workflow\n⭐⭐⭐⭐ Difficulty: Hard | ⏱️ Time: 30 minutes\n\n**Task:** Apply the full legacy code improvement workflow to add a new feature (fraud detection) to this payment processor.\n\n```java\npublic class LegacyPaymentProcessor {\n public String process(String cardNum, String amount, String currency) {\n if (cardNum == null || cardNum.length() != 16) return \"ERR_CARD\";\n BigDecimal amt;\n try {\n amt = new BigDecimal(amount);\n } catch (Exception e) {\n return \"ERR_AMOUNT\";\n }\n if (amt.compareTo(BigDecimal.ZERO) <= 0) return \"ERR_AMOUNT\";\n if (currency == null || !currency.matches(\"[A-Z]{3}\")) return \"ERR_CURRENCY\";\n\n String result = PaymentGateway.charge(cardNum, amt, currency);\n AuditLog.record(\"PAYMENT\", cardNum.substring(12), amt, result);\n return result;\n }\n}\n```\n\n**Steps:**\n1. Write characterization tests for current behavior\n2. Identify seams\n3. Add fraud detection using Sprout Class technique\n4. Integrate without modifying original logic\n\n**✅ Solution:**\n\n**Step 1: Characterization Tests**\n\n```java\npublic class LegacyPaymentProcessorTest {\n\n private LegacyPaymentProcessor processor;\n\n @BeforeEach\n void setUp() {\n processor = new TestableLegacyPaymentProcessor();\n }\n\n @Test\n void process_validPayment_returnsGatewayResult() {\n String result = processor.process(\"1234567890123456\", \"100.00\", \"USD\");\n assertEquals(\"SUCCESS\", result);\n }\n\n @Test\n void process_nullCard_returnsCardError() {\n String result = processor.process(null, \"100.00\", \"USD\");\n assertEquals(\"ERR_CARD\", result);\n }\n\n @Test\n void process_shortCard_returnsCardError() {\n String result = processor.process(\"123456789012345\", \"100.00\", \"USD\");\n assertEquals(\"ERR_CARD\", result);\n }\n\n @Test\n void process_invalidAmount_returnsAmountError() {\n String result = processor.process(\"1234567890123456\", \"invalid\", \"USD\");\n assertEquals(\"ERR_AMOUNT\", result);\n }\n\n @Test\n void process_zeroAmount_returnsAmountError() {\n String result = processor.process(\"1234567890123456\", \"0\", \"USD\");\n assertEquals(\"ERR_AMOUNT\", result);\n }\n\n @Test\n void process_invalidCurrency_returnsCurrencyError() {\n String result = processor.process(\"1234567890123456\", \"100.00\", \"usd\");\n assertEquals(\"ERR_CURRENCY\", result);\n }\n}\n```\n\n**Step 2: Identify Seams**\n\n```java\n// Seams identified:\n// 1. PaymentGateway.charge() - static, need preprocessing seam\n// 2. AuditLog.record() - static, need preprocessing seam\n\n// Create testable subclass\nclass TestableLegacyPaymentProcessor extends LegacyPaymentProcessor {\n String gatewayResult = \"SUCCESS\";\n String lastAuditAction;\n BigDecimal lastAuditAmount;\n\n @Override\n protected String chargeGateway(String cardNum, BigDecimal amt, String currency) {\n return gatewayResult;\n }\n\n @Override\n protected void recordAudit(String action, String cardSuffix, BigDecimal amt, String result) {\n lastAuditAction = action;\n lastAuditAmount = amt;\n }\n}\n\n// Modified legacy class (minimal changes)\npublic class LegacyPaymentProcessor {\n public String process(String cardNum, String amount, String currency) {\n // ... validation unchanged ...\n\n String result = chargeGateway(cardNum, amt, currency); // Changed\n recordAudit(\"PAYMENT\", cardNum.substring(12), amt, result); // Changed\n return result;\n }\n\n protected String chargeGateway(String cardNum, BigDecimal amt, String currency) {\n return PaymentGateway.charge(cardNum, amt, currency);\n }\n\n protected void recordAudit(String action, String cardSuffix, BigDecimal amt, String result) {\n AuditLog.record(action, cardSuffix, amt, result);\n }\n}\n```\n\n**Step 3: Sprout Class for Fraud Detection**\n\n```java\n// New class - fully tested from scratch\npublic class FraudDetector {\n\n private static final BigDecimal HIGH_RISK_THRESHOLD = new BigDecimal(\"5000\");\n private static final Set BLOCKED_BIN_PREFIXES = Set.of(\"400000\", \"411111\");\n\n public FraudRisk assess(String cardNumber, BigDecimal amount, String currency) {\n List risks = new ArrayList<>();\n int score = 0;\n\n // High amount check\n if (amount.compareTo(HIGH_RISK_THRESHOLD) > 0) {\n risks.add(\"HIGH_AMOUNT\");\n score += 30;\n }\n\n // Blocked BIN check\n String bin = cardNumber.substring(0, 6);\n if (BLOCKED_BIN_PREFIXES.contains(bin)) {\n risks.add(\"BLOCKED_BIN\");\n score += 100;\n }\n\n // High-risk currency\n if (Set.of(\"RUB\", \"NGN\", \"VND\").contains(currency)) {\n risks.add(\"HIGH_RISK_CURRENCY\");\n score += 20;\n }\n\n return new FraudRisk(score, risks, score >= 50);\n }\n}\n\npublic record FraudRisk(int score, List risks, boolean blocked) {}\n\n// Tests for FraudDetector\npublic class FraudDetectorTest {\n\n private FraudDetector detector = new FraudDetector();\n\n @Test\n void assess_normalPayment_lowRisk() {\n FraudRisk risk = detector.assess(\"5555555555554444\", new BigDecimal(\"100\"), \"USD\");\n assertFalse(risk.blocked());\n assertEquals(0, risk.score());\n }\n\n @Test\n void assess_highAmount_mediumRisk() {\n FraudRisk risk = detector.assess(\"5555555555554444\", new BigDecimal(\"6000\"), \"USD\");\n assertFalse(risk.blocked());\n assertEquals(30, risk.score());\n }\n\n @Test\n void assess_blockedBin_blocked() {\n FraudRisk risk = detector.assess(\"4000001234567890\", new BigDecimal(\"100\"), \"USD\");\n assertTrue(risk.blocked());\n assertTrue(risk.risks().contains(\"BLOCKED_BIN\"));\n }\n}\n```\n\n**Step 4: Integrate Without Breaking Original**\n\n```java\npublic class LegacyPaymentProcessor {\n private final FraudDetector fraudDetector;\n\n public LegacyPaymentProcessor() {\n this.fraudDetector = new FraudDetector();\n }\n\n // For testing\n public LegacyPaymentProcessor(FraudDetector fraudDetector) {\n this.fraudDetector = fraudDetector;\n }\n\n public String process(String cardNum, String amount, String currency) {\n if (cardNum == null || cardNum.length() != 16) return \"ERR_CARD\";\n BigDecimal amt;\n try {\n amt = new BigDecimal(amount);\n } catch (Exception e) {\n return \"ERR_AMOUNT\";\n }\n if (amt.compareTo(BigDecimal.ZERO) <= 0) return \"ERR_AMOUNT\";\n if (currency == null || !currency.matches(\"[A-Z]{3}\")) return \"ERR_CURRENCY\";\n\n // NEW: Fraud detection (sprouted integration)\n FraudRisk fraud = fraudDetector.assess(cardNum, amt, currency);\n if (fraud.blocked()) {\n recordAudit(\"FRAUD_BLOCK\", cardNum.substring(12), amt, \"BLOCKED\");\n return \"ERR_FRAUD\";\n }\n\n // Original logic unchanged\n String result = chargeGateway(cardNum, amt, currency);\n recordAudit(\"PAYMENT\", cardNum.substring(12), amt, result);\n return result;\n }\n\n // ... seam methods unchanged\n}\n```\n\n---\n\n## Interview Questions\n\n### Q1: How do you approach a legacy codebase?\n\n**Answer:**\n1. Find entry points (controllers, main, scheduled tasks)\n2. Trace execution path for the feature I need to change\n3. Write characterization tests to document current behavior\n4. Identify seams for testability\n5. Make small changes with tests\n6. Document discoveries for next developer\n\n### Q2: What's a \"seam\" in legacy code?\n\n**Answer:**\nA seam is a place where you can alter behavior without editing source code:\n- Object seam: Inject mock through constructor/setter\n- Subclass seam: Override protected method\n- Preprocessing seam: Extract factory method and override\n\n---\n\n## 📝 Summary\n\n| Technique | Purpose |\n|-----------|---------|\n| Scratch Refactoring | Understand through refactoring, then discard |\n| Finding Seams | Locate points for test injection |\n| Sprout Method | Add new code in new method |\n| Wrap Method | Add behavior around existing method |\n| Sprout Class | New functionality in new class |\n| Characterization Tests | Document current behavior |\n\n---\n\n## 📅 Review Schedule for This Article\n\n| Day | Task | Time |\n|-----|------|------|\n| Day 1 | Review the Legacy Code Workflow diagram | 5 min |\n| Day 3 | Redo Exercise 1 (Identify Seams) | 10 min |\n| Day 7 | Practice scratch refactoring on code from your project | 15 min |\n| Day 14 | Redo Debug This (The Flaky Test) | 10 min |\n| Day 30 | Apply Sprout Method to add a feature in your codebase | 20 min |\n\n---\n\n*Next: [Part 20: Characterization Testing]*\n","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:24.880544Z","createdAt","2026-06-10T07:19:24.881435Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes","estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Java","readingTime","seriesId","seriesOrder",19,"author",{"_31":54,"_97":56,"_98":99,"_100":101,"_102":-5,"_103":-5,"_104":-5,"_105":-5,"_106":-5},"category",{"_31":93,"_71":58,"_35":94,"_74":95,"_96":-5},"tags",[77,78,79,80],"series",{"_31":16,"_71":72,"_35":73,"_74":75,"_76":23},"name","Advanced Clean Code Patterns: From Principles to Production Mastery","advanced-clean-code-patterns","description","A comprehensive 26-part series covering enterprise-grade clean code patterns for Java developers. From SOLID principles and code smells through refactoring patterns, error handling, validation, to legacy modernization and modern Java 21+ features. Includes real production stories, mental models, exercises, and 150+ interview questions.","isActive",{"_31":90,"_71":91,"_35":92},{"_31":87,"_71":88,"_35":89},{"_31":84,"_71":85,"_35":86},{"_31":81,"_71":82,"_35":83},33,"Technical Debt","technical-debt",89,"Modernization","modernization",88,"Legacy Code","legacy-code",90,"Code Archaeology","code-archaeology",5,"java","Category for Java","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]