W28 - Definition & Interface Dependencies

The importance of definitions

In everyday work, many confusing or unclear matters often stem from problems in how concepts are defined. For example, a definition may be unclear, or it may be clear but not widely agreed upon. Take this example: when QA assigns an owner to a bug in OneS, in some complex scenarios they may not know who is appropriate to assign. The root cause of this confusion is an unclear definition of the term “assignee,” or a lack of consensus about it. Without a clear definition, we tend to interpret “assignee” as a composite concept that includes the person who created the issue, the person who handles it, and the person who is ultimately responsible. If the issue is even slightly complex, this naturally creates ambiguity with multiple meanings. A simple, clear definition often resolves the problem. For instance, the clearest principle is: assign it to whoever is responsible for fixing it — the assignee is the handler. This is unrelated to responsibility decomposition; finding root causes and assigning accountability is a matter for COE retrospectives.

The impact of inter-interface dependencies on backward compatibility

In a frontend-backend separated architecture, interface changes and iterations must pay careful attention to backward compatibility. Generally, backend API fields should only be added, not changed. If backward compatibility is not preserved, adjusting the release order of frontend and backend or adding a toggle to switch between old and new APIs will not prevent sudden failures at critical release points. Pay special attention to cases involving dependencies between interfaces: if you don’t modify an old API but create a new version, and that new API depends on a preceding interface — for example, the preceding interface provides the request address for the subsequent interface — then even adding an interface requires extra care. Ensure the preceding interface is version-compatible with the newly added subsequent interface.