Improving Code Quality - #69: My Code Quality Tips

To improve code quality, you should align with the understanding flow of the reader before the mindset of the writer. Rather than transcribing the implementation as-is, expose the core behavior and state changes at a shallow level so they're visible at a glance, and hide exception handling or auxiliary logic to keep the reading path simple.

You should also think first about structures that are hard to misuse. Express constraints through types or static verification whenever possible, rather than documentation, runtime validation, or tests, and if necessary, enforce return value checks to catch misuse early. This perspective matters not only when writing new code but also during extension and refactoring.

Since no principle is universal, you should examine the background and assumptions behind a principle before applying it. For example, keeping visibility narrow isn't always best — sometimes a private function reveals the overall flow better than a local function.

If a large refactor is realistically difficult, you should still leave behind an improvement within the (0, 1) range. Add comments or tests that describe the current behavior, document the ideal design and link it to a TODO or issue, and apply the better design to new code so it can serve as a reference implementation.

Finally, design, code, and documentation should be discussed while being built, not discussed only after completion. Having a culture that frequently addresses small issues builds the ability to put thoughts into words, allows ideas to be combined to reach better conclusions, and keeps knowledge from becoming closed off even outside the team.