Refactoring a Chat Assistant: Why the Hardest Part Is Deciding, Not Coding
This article recounts the design decisions made during a chat assistant refactoring, covering naming consistency, UI component conventions, minimal abstraction boundaries, decoupling output language from UI language, and package structure organization, emphasizing that good refactoring is a series of well-reasoned trade-offs documented with clear rationales.
1. Naming: Align Names on a Single Axis
The most time-consuming part of the refactoring was naming. A class name often required several rounds of debate. The classic example was the pair of clients: one named OpenAiCompatClient (by protocol) and another LocalClient (by deployment). Because the two names fell on different axes, readers couldn't tell if they were counterparts. Unifying on the deployment axis yielded CloudClient and LocalClient — symmetric, enumerable, and predictable.
Similar discussions included renaming a pseudo-repository AiRepository (which did no persistence, only orchestration) to AiService, and removing redundant prefixes inside packages: since the package was already ai.embedding, EmbeddingEngine became Encoder and EmbeddingCodec became VectorCodec.
One name changed three times before settling. LocalLlmEngine initially handled both the native engine and the call entry point — too heavy. It was split into LlmEngine (engine) and LocalClient (a thin AiClient wrapper), then moved into the ai.local package to align the naming axis. The lesson: don't fear renaming; fear letting a wrong name solidify into "nobody understands but nobody dares to touch."
2. Screen vs. View vs. Page: A Naming Convention Debate
Another debate centered on the suffix for full-screen UI classes. Candidates included HomePage, HomeView, and simply Home. Each was rejected for specific reasons: HomePage carries a web connotation; Android has no "Page" concept. HomeView is worse — View in Android specifically means a widget (e.g., TextView, ImageView), so using it for a full screen creates ambiguity. Home is too generic and collides with components, state, etc.
The team settled on HomeScreen, following the Jetpack Compose community convention where a Screen represents a full-screen destination. Three screens were unified as HomeScreen, AdvancedScreen, and MemoryScreen. The takeaway: prefer established conventions over invented names because conventions provide predictability — a newcomer sees the suffix and knows it's a full screen without guessing.
3. Where to Draw the Abstraction Line: Minimal Interfaces and Facades
The team discussed how much to abstract. The conclusion: not "more abstraction is better," but "open the smallest hole only on the axis of change." The memory layer only needed to "turn text into vectors, then store and retrieve," so it received a single Embedder interface (prepare, embed, encode, decode). Concrete implementations — Encoder, ModelAssets, VectorCodec — were hidden behind a private facade MnnEmbedder.
Benefits: the memory layer can use a fake Embedder for unit tests, swapping engines later requires zero changes to callers, and concrete classes remain invisible outside the package. The value of abstraction lies not in layer count but in shielding volatile details behind an interface.
4. A Product Decision: Output Language ≠ UI Language
During internationalization, a question arose: for an English-speaking user, what language should the AI reply in? The decision was to split this into two independent knobs: UI language follows the system locale, while reply language follows the conversation content. Thus, regardless of UI language, if the user writes in Chinese the assistant replies in Chinese; if English, then English. Implementation was a single prompt addition: "Reply in the language of the conversation."
Additionally, the team defined "what not to translate": keywords parsed from chat are used to match Chinese app UIs like WeChat and QQ; translating them would break matching, so they must stay in original form. The boundary of a decision can be more important than the decision itself.
5. Package Organization: Who Stays at the Root
The layered package structure went through iterations: ai and data/local were merged into aiprovider then split back to ai; the presentation layer was eventually moved from the root into ui.
A subtle discussion concerned AppBus (a cross-layer event bus). It is written by accessibility services and read by UI, belonging to no single layer — so it was left in the root package as an explicit "cross-layer connection point." Package structure is a map for humans; who lives in which layer and what serves as a connector should be visible at a glance.
Conclusion: Good Refactoring Is a Series of Well-Reasoned Trade-offs
Looking back, the real effort wasn't typing code but standing at each fork: which axis for this name, Screen or something else, how wide to open this abstraction, which knob controls language. Every decision should leave a "why" so the next person doesn't have to re-guess. That, perhaps, is what refactoring should ultimately leave behind.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
