User:BPirkle (WMF)/Code Cleanup FY2019 Q3

This document describes steps the Core Platform Team will take in Q3 of fiscal year 2018-2019 towards our TEC13 goal of reducing Technical Debt.

Our Technical Debt is large, and it is not realistic to retire it all in one quarter. A modest but achievable improvement is more valuable than a large but unachievable one. So in Q3, we will make targeted changes to specific types of Technical Debt in high-priority areas of the codebase.

We will

We will focus on specific aspects of code cleanup:

• Remove references to deprecated code
• Remove deprecated code per our Deprecation Policy
• Identify and document components
• Favor the following patterns/principles: Dependency Injection, Immutable Objects, and Stateless Services
• Add additional tests, particularly integration testing

We will not

For achievability, we will explicitly not do certain things:

• Add new functionality, or significantly modify existing functionality
• “Blue sky” or “white page” refactoring
• Large-scale rearchitecting or restructuring
• Achieve 100% completion across the codebase even within the specific focus areas

Details

• References to deprecated code are obvious “low hanging fruit” in technical debt reduction. These references block removal of deprecated code, provide in-code Anti-patterns that developers may inadvertently reproduce, and are never the preferred implementation (or else that code would not be deprecated in the first place).

• Removing deprecated code from the codebase is a powerful tool for retiring Technical Debt. It permanently removes the possibility that the deprecated code will be inadvertently referenced, and reduces the amount of code that must be read, understood, transmitted, and processed by our developers and servers.

• A component, for purposes of this document, is a cohesive set of code with no circular dependencies on any other code. This definition, while not technically rigorous or universally applicable, provides a guideline for identifying potential components. Mechanisms to group code into components include classes, namespaces, and directories. Some refactoring to separate code into components is in scope, but major refactoring is not. Our efforts will pragmatically focus on formalizing existing components (including unrecognized ones we may discover) rather than broader restructuring to create new components.

• Use of software design patterns helps provide consistency of implementation and code quality across our codebase. The patterns listed all help in reducing global state, encouraging implementations that can be cleanly divided into components, and managing code complexity. More details are available in the Decoupling document.

• Cleanup often touches many unrelated functional areas. It is challenging to manually verify proper behavior of all affected code.

• Automated test coverage helps protect against accidental breakage. Integration testing, which confirms cross-system behavior rather than just one individual class or subsystem, is particularly useful. This is not to say that manual testing will not also be performed, but instead to say that we want as much verification as is reasonably possible.

Scope

TEC13 applies to our entire codebase. However, thoroughly analyzing our entire codebase for areas in need of cleanup could easily consume all our available time in Q3. To achieve real results, we will prioritize existing cleanup-related Phabricator tickets, and especially cleanup opportunities introduced by the recent MCR project. Implementers will have the freedom to also address any other areas discovered in the course of this effort, subject to the guidelines defined in this document and the time available. Cleanup opportunities that cannot be addressed within Q3 can be documented via a suitably tagged Phabricator task for future attention.