Engineering Maintainable WordPress Websites

Presentation slide from WordCamp Taiwan 2025. Kaohsiung. 2025-11-07 to 08.

---

Too many WordPress sites work at launch but break during updates or extensions, causing extra work and frustration for clients and developers. In this session, we’ll explore practical ways to engineer WordPress sites for long-term maintainability, covering development practices, documentation, plugin choices, and workflows that make sites easier to update, extend, and trust.

https://taiwan.wordcamp.org/2025/session/engineering-maintainable-wordpress-websites/

Transcript

1. Engineering Maintainable WordPress Websites WordCamp Taiwan 2025 Toru Miki
2. What I do • Web Developer at Tarosky - Tokyo based, client work, maintenance support, auto-scaling WordPress platform service. • Mid- Large- scale WordPress websites • I develop moving sites, making sites. • Currently mostly backend but not limited to
3. Not updated 😭 Cannot update or update breaks 🫤 10,000 errors per minute 😲 No one know why plugin x is used 🫣
4. Built to work, not to last. Maintained to just run, not to improve.
5. Frustrating 🤬 Hurts both us and clients 😫💸
6. Contents Applications WordPress is CMS. Maintenance matters.
7. Many bad experiences with WordPress arise from poor maintainability.
8. Practical Practices • Error Logs are Gold • Principles of Plugin Selection • Separation of Concerns • Development Practices
9. Error Logs are Gold
10. Stop relying on guessworks! • Logs tell you what actually happened — not what you think happened • Make sure logs are accessible and viewable • Make it part of your work fl ow
12. Principles of Plugin Selection
13. Look beyond the feature list, to evaluate long- term viability • Prefer single-purpose. Opt for focused solutions. Avoid bloated. • Responsively maintained. Timely fi xes (esp. security issues), and honest support. Not fl ashy but reliable. • Quality matters — secure, well-written (and scalable) code.
14. From WordPress.org plugin repository of a plugin…
15. IUUQTHJUIVCDPNWFLUPSJODMJHIUOJOHJTTVFT
16. Look beyond the feature list, to evaluate long- term viability • Always keep in mind! • You are effectively handing off functionality and maintenance of this part completely to someone else! • ؙ౤͛ (maru-na-ge) • 㟚แ • Know when to not to rely on 3rd party
17. Separation of Concerns
18. Organize code so each part has a clear, single responsibility • Good Practices • Keep each function, class, or fi le focused on a single, well-de fi ned purpose. (Single Responsibility Principle, SRP) • Theme = Presentation. Plugin = Functionality. • Custom features in dedicated, single-purpose plugin. • Functionality is visible and discoverable.
19. // Main Unit Update Notification OFF add_filter('pre_site_transient_update_core', '__return_zero'); remove_action('wp_version_check', 'wp_version_check'); remove_action('admin_init', ‘_maybe_update_core'); // Plugin Update Notification OFF add_filter("pre_site_transient_update_plugins", "__return_null"); // Hide Unnecessary Menus add_action('admin_menu', 'remove_menus'); function remove_menus() { remove_menu_page(‘index.php’); . . . }
20. Organize code so each part has a clear, single responsibility • Bad Practices • Functions, classes and fi les handling multiple unrelated tasks. • Custom features buried inside functions.php • Mixing presentation and logic. E.g. custom post type de fi ned in the theme • Hard to see what custom functionality exists or where it lives
21. Development Practices
22. Adopt tools and work fl ows from the broader software engineering world • Version Control • Use Git to track every change and maintain a clear, revertible history. • Pull Request (PR) based work fl ow • Work through PR — even solo — to group related changes and trigger automations.
23. Adopt tools and work fl ows from the broader software engineering world • Static Analysis • Apply tools like PHPCS, ESLint, Stylelint to enforce coding standards • Testing • Add tests where possible, to prevent regressions, and ensure stability
24. Adopt tools and work fl ows from the broader software engineering world • Documentation • Write lightweight docs (PHPDocs!) to ease future maintenance. • CI/CD • Setup automated pipelines for consistent and safe deployments • PR triggering running of the static analysis and tests • Build & deploy directly from the repo — no need to do SFTP
25. Let’s build better
26. — Software Engineering at Google Within Google we sometimes say, “Software engineering is programming integrated over time.” Programming is certainly a signi fi cant part of software engineering: after all, programming is how you generate new software in the fi rst place. If you accept this distinction, it also becomes clear that we might need to delineate between programming tasks (development) and software engineering tasks (development, modi fi cation, maintenance). The addition of time adds an important new dimension to programming. Cubes aren’t squares, distance isn’t velocity. Software engineering isn’t programming 26
27. Let’s engineer WordPress sites that last — fewer headaches for developers, better experiences for clients
28. From Q&A When you encounter PHP fatal error like these: PHP Fatal error: Allowed memory size of xxxxxx bytes exhausted (tried to allocate xxx bytes) in /var/www/wordpress/wp-includes/wp-db.php on line 2007 Give this plugin a try. It was developed by my colleague (CTO) to help analyze the error by recording which requested URL this happened. You can then further investigate. https://wordpress.org/plugins/hagakure/
29. Thank you! Questions? Toru Miki toru.miki@tarosky.co.jp