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.

[By Jelleke Vanooteghem on Unsplash]

I understand why code quality and fast review cycles matter.

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.

I take on small tasks.

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 prepare my local development environment.

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.

I read the existing code.

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 plan my code.

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 write lots of ugly code.

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.

I refactor for readability.

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 perform manual tests after refactoring.

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.

I review my own draft code review before opening it.

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.

I include the why in the code review description.

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..."

I include the what in the code review description.

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

I listen to code review comments with a radically open mind.

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.

Bottom line: I take pride in my code.

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. 🎨

Like this article?

It started on Twitter. Follow me for more! Here's an example of what to expect: