Why Legacy Code Is Killing Your Productivity—and How to Fix It

Introduction

For a long time we have been showcasing framework usage and source‑code analysis to improve our overall skills, but we rarely focus on code‑quality governance.

In practice, the biggest challenge for developers is not learning new technologies but maintaining legacy code.

Below are several memorable projects I have taken over.

Case Sharing

2.1 Certain Platform Query Code

The query is simple but a nightmare for maintainers.

The SQL runs slowly (2‑3 seconds) and the service layer adds further logic, making it even slower as data grows.

Because the query is used in many places, changing it requires understanding every field and retesting.

About 90% of the code in this project follows this style.

Another query method uses a Map to receive objects without encapsulating a database entity, making the code hard to read and understand.

2.2 Certain Platform Report Query

The method is a stored procedure with over 1,000 lines, which can intimidate newcomers and makes adjustments painful.

2.3 Microservice API Package Inter‑dependency

Microservices are ubiquitous, but they must be used correctly.

Typical layering for an order microservice:

order
    |- api (src/main/java)
    |    |- request
    |    |- response
    |    |- enums
    |    |- api
    |
    |- provider (src/main/java)
    |    |- constant
    |    |- entity
    |    |- dao
    |    |- service
    |    |- api
    |
    |- provider (src/main/resources)
    |    |- mapper
    |    |- application.properties
    |    |- application-dev.properties

The api package only exposes service interfaces, while the provider package implements the business logic. api package: stores service interface definitions, request and response entities; it is pure. provider package: implements the interfaces, contains business logic similar to a traditional web project.

Incorrectly, some teams let api depend on provider, causing circular dependencies such as order‑api ↔ stock‑api, which leads to jar conflicts at startup.

The proper approach is for the provider module to depend on api, not the other way around, keeping the api jar independent.

Conclusion

Teams must define coding standards and avoid unreadable, tightly coupled, or overly complex code. Follow guidelines such as clear module hierarchy, interface‑driven design, minimal inheritance, single‑table queries, and one‑to‑one mapping between entity classes and database tables.

The goal is to make the codebase approachable even for an intern, rather than burdening developers with convoluted solutions.