Refactoring Problematic Code for Maintainability

🎄 Day 21 of the #AdventOfOR 2025! Today, we shift from "how it runs" to "how it’s built." We’re moving from the mindset of writing a "math script" to the mindset of software engineering. I sat down with Dr. Tim Varelmann, who once inherited a 2,500-line optimization codebase that was an unmanageable tangle. By applying algebraic modeling principles, he refactored it down to just 48 lines. The secret? #Optimization isn't just math: it's software. And high-quality software is never accidental. In today’s interview, Tim and I discuss: 🧹 The gap between model and adoption 📐 Engineering practices that keep #OperationsResearch systems maintainable ✨ Modeling patterns that prevent technical debt 🎯 How algebraic modeling enforces good engineering naturally 🐍 GAMSPy at the intersection of modeling + engineering 📚 10 years of lessons packaged into 10 hours 🫵 Your turn: Think about the last model you built. If you had to hand it over to a colleague today, what is the "messiest" part they would struggle to maintain? Is it hard-coded constants? A giant, tangled file? Or data cleaning that feels like archaeological work? Let’s talk about the "maintenance headache" in the comments. 👇

About five years ago, I had a junior engineer on my team who was brilliant but struggled so much he was about to have a low performance review. Let’s call him Anthony He was fresh out of college and eager to prove himself, but his code reviews often came back with extensive feedback. The root of the issue wasn’t his intelligence or effort it was his approach. Anthony had this habit of jumping straight into the deep end. He wanted his code to be optimized, elegant, and perfect from day one. But in that pursuit, he often got stuck either over-engineering a solution or ending up with something too complex to debug. Deadlines were slipping, and his confidence was taking a hit. One day, during a particularly rough code review, I pulled him aside and shared a principle that had profoundly shaped my own career: “Make it work, make it right, make it fast.” I explained it like this: 1. Make it work – First, solve the problem. Forget about how pretty or efficient your code is. Focus on meeting the acceptance criteria. If it doesn’t work, nothing else matters. 2. Make it right – Once it works, step back. Refactor the code, and make it clean, modular, and maintainable. Code is for humans who’ll work with it in the future. 3. Make it fast – Finally, if performance is critical, optimize. But don’t sacrifice clarity or maintainability for marginal speed gains. The next sprint, he followed this approach on a tricky API integration task. When we reviewed his work, the difference was night and day. Not only had he delivered on time, but the code was a joy to read. Even he admitted it was the least stressful sprint he’d had in months. Six months later, Anthony came to me and said, “That principle you shared, it’s changed everything. Thank you for pulling me aside that day.” Today, Anthony is a senior engineer leading his team, mentoring others, and applying the same principle that once helped him. We’re still on good terms though he moved to another org. Sometimes, the most impactful advice is the simplest. As engineers, we often get caught up in trying to do everything perfectly all at once But stepping back and breaking it into manageable steps can make all the difference.

I'm a Software Engineer at AWS, and here are 18 lessons I learned about refactoring code over the last 7 years in 60 seconds. It took me a lot of mistakes to learn these, so you don't have to: 1/ Never assume how code behaves → verify it with tests before changing anything 2/ Refactor in small, reversible steps → big rewrites break things. 3/ Don't change too much at once → reduce the blast radius 4/ Use AI as a refactoring partner → set guardrails, verify with tests, and iterate in small steps 5/ Test before refactors → they protect behaviour, not implementations. 6/ Keep it simple (KISS) → most complexity is accidental 7/ Fix design problems, not symptoms → good architecture prevents bugs 8/ Keep your code DRY → duplication multiplies risk 9/ Performance matters → refactoring isn't just structure, it's behaviour at scale 10/ Legacy code isn't scary → changing it blindly is 11/ Know your goal before refactoring → clarity beats activity 12/ Readable code beats clever code → readable code is easy to maintain in production 13/ Favour composition over inheritance → inheritance adds more complexity 14/ Patterns aren't always your friend → context matters more than theory 15/ Code is for humans → future readers are part of your system 16/ Refactoring is a habit → it's how systems stay healthy over time and avoid "broken windows" 17/ Messy code is a liability → technical debt compounds quietly. 18/ Refactor the code you touch most → optimise for where teams spend time. P.S. What else would you add? --- 🔖 Save this for the next time you're about to "just clean it up" ➕ Follow Abdirahman Jama for practical software engineering tips. #softwareengineering

𝗛𝗼𝘄 𝘁𝗼 𝗿𝗲𝗳𝗮𝗰𝘁𝗼𝗿 𝗹𝗲𝗴𝗮𝗰𝘆 𝗰𝗼𝗱𝗲 𝘄𝗶𝘁𝗵 𝘁𝗵𝗲 𝗦𝘁𝗿𝗮𝗻𝗴𝗹𝗲𝗿 𝗙𝗶𝗴 𝗽𝗮𝘁𝘁𝗲𝗿𝗻 The Strangler Fig pattern allows you to grow new implementations around risky legacy code. Martin Fowler coined the metaphor after seeing vines that wrap around a host tree and eventually replace it. Instead of a risky “big-bang” rewrite, you wrap the old code with a thin layer, route new traffic to modern implementations, and retire the legacy code when coverage reaches 100%. Here are the steps to strange legacy code: 𝟭. 𝗘𝘅𝗽𝗼𝘀𝗲 𝗮 𝘀𝗹𝗶𝗺 𝗶𝗻𝘁𝗲𝗿𝗳𝗮𝗰𝗲.Define the future API in a new class or adapter. No state moves yet; you’re just sketching the contract. 𝟮. 𝗥𝗲𝗱𝗶𝗿𝗲𝗰𝘁 𝗰𝗮𝗹𝗹𝗲𝗿𝘀. Point controllers, services, or endpoints at the new interface. The old class fades into the background. 𝟯. 𝗦𝗽𝗶𝗻 𝘂𝗽 𝗮 𝗻𝗲𝘄 𝗱𝗮𝘁𝗮 𝘀𝗼𝘂𝗿𝗰𝗲. Add the table, topic, or microservice that will own the extracted state. AWS and Azure both frame this as creating a “target” boundary. 𝟰. 𝗗𝗼𝘂𝗯𝗹𝗲-𝘄𝗿𝗶𝘁𝗲 (𝘀𝗵𝗮𝗱𝗼𝘄 𝘄𝗿𝗶𝘁𝗲𝘀). Within a single transaction, write to both the legacy and new stores. This keeps rollback trivial and lets you diff live traffic. 𝟱. 𝗕𝗮𝗰𝗸𝗳𝗶𝗹𝗹 𝗵𝗶𝘀𝘁𝗼𝗿𝘆. Batch-copy existing rows. Lock records or use idempotent upserts to stay consistent during the move. 𝟲. 𝗙𝗹𝗶𝗽 𝘁𝗵𝗲 𝗿𝗲𝗮𝗱𝘀. Switch getters to the new store. Monitor error budgets and latency; feature flag if you need a fast escape hatch. 𝟳. 𝗥𝗲𝗺𝗼𝘃𝗲 𝗹𝗲𝗴𝗮𝗰𝘆 𝗽𝗮𝗿𝘁𝘀. Delete legacy columns, routes, and test fixtures. Celebrate with green builds and simpler onboarding docs. Big-bang rewrites look heroic but often end as zombie projects. The Strangler Fig pattern enables you to refactor safely, deliver value continuously, and maintain a cleaner codebase every sprint. 

Best Practices for Writing Modular and Reusable Code ➊ Design ➟ Single Responsibility Each module/class/function should do one thing. This is the core of the Single Responsibility Principle (SRP), a pillar of SOLID design. ➟ Loose Coupling Modules should have minimal dependencies. This ensures easier reuse and lower maintenance cost. ➟ High Cohesion Related functionality should be grouped together for better clarity and maintainability. ➋ Structure ➟ Small Functions Functions should do one thing and do it well. This improves readability and testability. ➟ Clear Interfaces Well-defined APIs/interfaces enable easy integration and replacement. ➟ Consistent Naming Using consistent, descriptive names helps other developers understand the code quickly. ➌ Reuse ➟ Libraries Common functionality should be abstracted into libraries/modules. ➟ Generic Code Use parameterization/generics/templates where appropriate to maximize reuse. ➟ Configuration Avoid hardcoding values, use configs for flexibility. ➍ Testing ➟ Unit Tests Essential for verifying small, isolated pieces of code. ➟ Mocking Facilitates testing in isolation, independent of dependencies. ➟ Coverage Strive for high test coverage to ensure reliability. ➎ Documentation ➟ Comments Explain why (not just what) in the code. ➟ Readme Every module/library should have clear usage instructions. ➟ Examples Usage examples are extremely helpful for onboarding and adoption. ➏ Maintainability ➟ Refactor Regularly Tackle technical debt before it grows. ➟ Code Reviews Peer reviews catch issues and spread knowledge. ➟ Follow Standards Consistency (via code style guides and conventions) prevents confusion.

I just reviewed 47 PLC programs from different plants. 43 were maintenance nightmares. Here's what the other 4 did differently: Most engineers think PLC code is just about making machines run. What you think? Your code will be read 100 times more than it's written. Yet 90% of control engineers treat it like a "write once, forget forever" script. The result? 3 AM emergency calls. Hours wasted deciphering logic. Production losses that could've been avoided. Here's the uncomfortable truth most won't tell you: Bad PLC structure costs companies $50K-$500K annually in downtime and troubleshooting time. So how do the top 10% structure their code? They follow the MODULAR framework: → Separate by Function I/O handling, interlocks, sequences, alarms, communications—each gets its own task. No spaghetti code mixing everything together. → Use UDTs (User Defined Types) Group related data.  Motor_Type includes status, speed, faults. One structure, infinite reusability. → Deploy AOIs/Function Blocks Write once, use everywhere. Your valve logic shouldn't be rewritten 47 times across the plant. → Naming Conventions Are Non-Negotiable PB_Start_Conveyor_01 beats Input_47 every single time. Future-you will thank present-you. → Initialization Blocks Set default states on startup. Prevent the "why is this valve open?" mystery. → Status Bits & Simulation Mode Build in diagnostics. Allow testing without physical I/O. Your commissioning team will worship you. → Comment Like You're Teaching Not "Motor start"—write "Starts conveyor motor after safety interlock confirmed and upstream buffer ready." The bottom line? Maintainable code isn't about being fancy. It's about respecting the next person who opens your program—even if that person is you in 6 months. Remember this: Code is read by humans and executed by machines. Optimize for the human first. Don't let THIS be your legacy. Don't let your code become someone else's nightmare. The time to build it right is NOW—not when everything's on fire. P.S. Have you inherited nightmare code? Share your horror story below! 👇 (We've all been there...) Save this post for your next project. Your future self will thank you! Tag someone who needs this! (Repost for others ♻️) #PLCProgramming #Automation #IndustrialAutomation #Engineering #Manufacturing #SystemsIntegration #Maintenance #PLCSupport

The most important prompt when coding with AI: "Scan the codebase for files over 600 lines." Then: "Modularize X to improve maintainability, scalability, and ease of editing." Most people blame the AI when their code breaks. But 90% of the time, the problem isn't the model, it's the codebase. Large files are the silent killer of AI-assisted development. Here's what actually happens when you ask an AI to edit a 2,000-line file: → The model can't hold all the logic in its context window at once → It misses dependencies between functions scattered across hundreds of lines → It "hallucinates" fixes that conflict with code it can't fully see → You spend more time debugging AI output than you saved by using it I ran a scan on one of our projects and found 10 files over 600 lines. The worst offender? A views.py at 2,438 lines. That single file was the root cause of most of our AI-assisted coding frustrations. The solution is simple: modularize before you prompt. Break large files into focused, single-responsibility modules. Keep each file under 300-500 lines. Group related functions together. Give files clear, descriptive names. Once you do this: → AI understands your code fully, no missing context → Changes are isolated, one edit doesn't cascade into 5 bugs → Code reviews become easier, for both humans and AI → Your prompts get simpler, "refactor this file" actually works This is the difference between fighting your AI tools and flowing with them. Try it on your next project. Scan for large files first. Modularize. Then prompt. You'll never go back.

A specialty manufacturer and distributor came to us with a common problem: too many consultants had touched their NetSuite. The result? Dozens of overlapping scripts Conflicting logic in approvals and purchase orders Duplicate commission calculations Errors in tariff and inbound shipment handling Transactions were lagging, approvals broke, and users didn’t trust the results. ZenSuite Partners cleaned house with a script refactoring project: Consolidation: Identified duplicate logic across multiple scripts and merged them into a single, streamlined process. Conversion: Migrated legacy scheduled scripts into User Event scripts so they ran more efficiently and consistently across records. Optimization: Rewrote inefficient code loops and added governance-friendly batching to reduce timeouts. Error Reduction: Repaired approval flows, eliminated duplicate purchase order creation, and rebuilt commission calculation logic. Maintainability: Reduced script count, improved naming conventions, and documented the environment so future admins wouldn’t repeat the same mistakes. The Outcome: -Faster transaction processing -Fewer calculation errors -Approvals that worked as intended A leaner, more reliable scripting environment that finance and operations could trust. #NetSuite #DigitalTransformation #Finance #BusinessSystems #ZenSuitePartners

Here’s how to clean up messy frontend and backend code—for good: ☑ Frontend Refactoring (React, Vue, Svelte) 1. Modularize the UI → Break large components into smaller, reusable ones → Use component libraries (like Storybook) to enforce consistency 2. Tame the State Monster → Ditch prop drilling for Context, Zustand, or Vuex → Clean up unused state and only lift when necessary 3. Prevent Useless Renders → Use memo, useMemo, useCallback, or Vue’s computed → Code-split and lazy load for faster UX 4. Modernize Your Styles → Try Tailwind, CSS-in-JS, or scoped styles in Vue → Remove dead CSS and centralize theme tokens 5. Lint It or Regret It → Add ESLint, Prettier, and TypeScript for sanity → Automate formatting in CI 6. Shrink Your Bundle → Enable tree shaking, dynamic imports, and minification → Tools like Vite, Webpack, or esbuild make it easy — ☑ Backend Refactoring (Node, Express, Nest, Django, Rails) 1. Modular by Design → Use MVC or Hexagonal to separate concerns → Prefer grouping by feature, not layers 2. Service Layer FTW → Keep business logic out of controllers → Easier to test, scale, and maintain 3. Database Speed Boost → Add indexes, cache smartly (Redis), and avoid N+1 queries → Normalize or denormalize based on query patterns 4. Make Your APIs a Joy to Use → Use pagination, filtering, and proper HTTP status codes → REST is great—but consider GraphQL for flexibility 5. Go Async or Go Home → Offload heavy work to queues (Bull, Sidekiq, Celery) → Use async/await where I/O blocking hurts 6. Test. Then Test Again. → Split large functions into testable units → Write unit + integration tests and run them on every commit — Cross-Cutting Musts → Atomic commits with clear messages → API docs with Swagger or JSDoc → Automate tests and linting with CI/CD — Refactoring isn’t just technical debt cleanup—it’s developer self-respect. If this helped, repost to help clean up someone else’s codebase too. Or DM me if you want to apply these to your stack.

𝗙𝗿𝗼𝗺 𝗖𝗵𝗼𝗿𝗲 𝘁𝗼 𝗖𝗵𝗮𝗺𝗽𝗶𝗼𝗻: 𝗛𝗼𝘄 𝗔𝗜 𝗶𝘀 𝗙𝗶𝗻𝗮𝗹𝗹𝘆 𝗠𝗮𝗸𝗶𝗻𝗴 𝗥𝗲𝗳𝗮𝗰𝘁𝗼𝗿𝗶𝗻𝗴 𝗮 𝗡𝗼-𝗕𝗿𝗮𝗶𝗻𝗲𝗿 Refactoring keeps systems alive, but it is often seen as a cost center: slow, risky, and delaying feature delivery. That is changing. With AI (specifically Cursor) built directly into the refactoring workflow, it is no longer just about cleaning up code. It is about doing it faster, safer, and with measurable business impact. I have never been a fan of the phrase "tech debt". It makes it sound like engineers are the ones who owe something. In reality, the debt belongs to the product or platform. Paying it down almost always improves productivity, quality, maintainability, or all three. Here are four practical ways AI is transforming refactoring:  • 𝗔𝘂𝘁𝗼𝗺𝗮𝘁𝗲𝗱 𝗗𝗲𝗽𝗲𝗻𝗱𝗲𝗻𝗰𝘆 𝗨𝗽𝗴𝗿𝗮𝗱𝗲𝘀  AI analyzed the codebase, upgraded critical libraries, handled breaking changes, and generated migration code. Days of manual work and the risk of human error disappeared.  • 𝗣𝗿𝗼𝗮𝗰𝘁𝗶𝘃𝗲 𝗦𝗲𝗰𝘂𝗿𝗶𝘁𝘆 𝗛𝗮𝗿𝗱𝗲𝗻𝗶𝗻𝗴  Instead of waiting for a fire drill, AI flagged context-specific vulnerabilities such as deprecated authentication methods and provided fixes instantly, strengthening security posture.  • 𝗧𝗮𝗿𝗴𝗲𝘁𝗲𝗱 𝗦𝘁𝗿𝘂𝗰𝘁𝘂𝗿𝗮𝗹 𝗜𝗺𝗽𝗿𝗼𝘃𝗲𝗺𝗲𝗻𝘁𝘀  AI mapped out modularization opportunities such as splitting a monolith and even provided starter code for the new services. This enabled incremental modernization without a risky full rewrite.  • 𝗚𝗲𝗻𝗲𝗿𝗮𝘁𝗶𝗻𝗴 𝗮 𝗥𝗲𝗴𝗿𝗲𝘀𝘀𝗶𝗼𝗻 𝗦𝗮𝗳𝗲𝘁𝘆 𝗡𝗲𝘁  The biggest blocker to refactoring is fear of breaking things. AI generated a suite of unit and integration tests, creating an automated safety net that boosted deployment confidence. The impact:  • Reduced critical vulnerabilities  • Modernized core systems without slowing feature delivery  • Increased developer velocity by freeing engineers to focus on user-facing features Refactoring is not just easier with AI. It now has clear ROI. It shifts from being a necessary evil to a strategic advantage. I am curious. Has your team applied AI in similar modernization work? What has been the most impactful result? #AIinPDLC #Refactoring #TechDebt #DeveloperProductivity #LegacySystems #DigitalTransformation #SoftwareEngineering