How I craft beautiful code that gets approved on the first review

At the start of my career I’d open a code review (a.k.a., Pull Request) and receive 50+ comments. I’d open a second revision, only to receive another 30.

It often took 8, 9, even 10 reviews to get my code approved. My code had some serious flaws and readability gaps. Occasionally, my peers had to rewrite it.

Fast forward to present day.

I’ve been a software engineer for 6 years. In my last year at a FAANG, 90% of my code changes were approved on the first review.

Getting that number to 100% isn’t the end goal. It’s outside of my control. Projects shuffle. Humans make mistakes. Reviewers have unique preferences, and insights on different parts of the codebase. Feedback is always welcomed.

The goal is to write functional, readable, maintainable code. Beautiful code — in your unique way of defining what that means. In aggregate, this will drive faster approvals and fewer revisions over time.

What follows is my step-by-step process on how I craft beautiful code. It’s worked for me, and may work for others.

Photo by Johnny Magrippis on Unsplash.

We read code many times more than we write it. Our code must be functional and readable, so our team can better maintain it and add features.

Flawed, unreadable code is difficult to maintain.

It causes review churn, which results in delayed delivery and distractions for my teammates.

The process starts before any code is written.

Small code changes are easier to review. They start with atomic, granular tasks.

Bad task:

  • UpdateWidget API

Better, not perfect:

  • ✅ Database model
  • ✅ API request model
  • ✅ Data Access Object (DAO) implementation
  • ✅ Auth
  • ✅ API implementation

Sometimes my initial task breakdowns don’t translate into well-scoped code reviews. I learn as I go.

I pull down the latest code. I ensure the tests pass. I configure my IDE to work smoothly, without false warnings.

This saves time and confusion while coding. A clean, functional environment strengthens my flow and focus.

Before implementing UpdateWidget, I observe the codebase to understand the current paradigm.

  • What design patterns are present? Can they be leveraged?
  • Are there any important conventions I should uphold?
  • Is there code from GetWidget or UpdateItem that should be reused?

I write skeleton interfaces, classes and methods for the abstractions that define my code structure.

I realize I won’t get this perfect, and I may need to refactor later. It gets me started.

I try to use decent names, but only spend a few seconds on them. They help me keep track of things when I refactor later.

I write unit tests at around the same time. I watch each test go red first, then to green.

I rarely perform manual tests during this step. Too tedious.

This is where I finalize my class and function abstractions.

Every decision is intentional: Why’d I choose this name for my function? Why’d I choose a BATCH_SIZE of 5, and not another value? Why’d I log at the WARN level, and not ERROR?

If anything looks weird or awkward, I search or ponder for an elegant solution. This includes the implementation and unit tests.

I make sure all the classes and functions are connected properly.

I cover basic functionality. I don’t rely on catching granular edge cases with this step. These should be covered by the unit tests.

Not in my IDE — in an internet browser. This gets me into “review mode.” The change of environment helps me read my code with more scrutiny.

I recreate the code review if I find a flaw. The code should work, and cover edge cases. I hold myself to a relentless standard for readability. But I’m pragmatic, not a perfectionist.

This describes the problem solved by the change.

It should implicitly answer these questions:

  1. Why is the problem worth solving?
  2. Why did I choose to solve it this way?
  3. Why did I choose the tradeoffs I did?

Sometimes I don’t have time to polish my code, or refactor as much as I’d like. I need to sacrifice readability so I can ship. I call out those situations here. “If I had more time, I would…”

The what describes the enhancement or fix introduced by the change.

This should be brief and concise. The reviewer should understand the what by looking at the code. Verbosity here is a sign that the code isn’t readable, or isn’t appropriately scoped.

If relevant, I might include the following:

  • Related tickets, PRs, issues
  • Test coverage
  • Screen captures
  • Rollback safety
  • Backwards compatibility

Feedback is inevitable. I embrace it from my peers — including the nitpicks.

Even if the feedback is incorrect, I listen to it.

“How do I know I’m right? Did my code cause confusion? If so, how can I clarify my code to prevent it?”

This process almost always exposes a lack of clarity in my code. I leverage the reviewer’s perspective to improve its readability. This is a significant accelerator to my skills over time.

I focus on what I can control: writing great code, and opening a clear and unambiguous code review.

At the beginning of this post I used the words craft and beautiful.

Coding is a craft. It’s a form of logic-based creativity. Every task, every new feature is a blank canvas. It’s an opportunity to demonstrate my abilities and produce something beautiful.

Beautiful is subjective. What’s beautiful to me, likely won’t be to you. You may even think my code is the antithesis of beauty, and that’s OK.

You’ll have to decide what beautiful means for yourself. It’ll change over time. For now, decide that each code review you open will be something you’re proud of. Every time.

So, now it’s your turn. Go craft some beautiful code. 🎨

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Curtis Einsmann

Software engineer; solopreneur. Writing to help developers level up. All stories free. Follow me on Twitter for more: https://twitter.com/curtiseinsmann