When I was a jr engineer at AWS my PR’s went through 100+ comments and 7+ revisions due to poor code quality. The friendly, helpful feedback helped me improve.
Now as a mid-level I tend to ship code in <= 2 revisions with minimal comments.
Here’s how I’m doing it. 🧵👇
1️⃣ I understand why code quality matters.
We read code 10x more than we write it. Our code must be understandable so our team can maintain and add features.
Poorly written code causes PR churn, which results in delayed delivery and can block other team members.
👇
2️⃣ I take on small tasks.
A good PR starts before any code is written. The task should be small, resulting in an easily reviewable PR.
Bad task: UpdateWidget API
Better: split into 4 separate tasks - UpdateWidget model; AuthN/AuthZ; input validation; implementation
👇
3️⃣ I invest time up front to ensure my local development environment is ready to code effectively.
- Pull down the latest code.
- Ensure local builds and tests are passing.
- Configure my IDE to working smoothly.
This saves time and headaches while coding.
👇
4️⃣ I read the existing code.
Before implementing UpdateWidget, I look in the codebase to understand the current paradigm.
What design patterns are being used? Is there code from GetWidget or UpdateItem that should be reused? Will refactoring be necessary?
👇
5️⃣ I plan my code.
I write skeleton interfaces, classes and methods for my code structure.
I realize I won’t get this perfect, and may need refactoring later. But it gets me started.
👇
6️⃣ I write lots of ugly code.
I try to use decent names. This way I know where things are when I read, iterate and refactor later.
I write automated unit tests. Manual testing during this step is tedious, time consuming, and leaves the door open for bugs during refactor.
👇
7️⃣ I refactor heavily.
This is where I name intelligently. I segment the code into small functions and finalize my class structure. If anything looks weird or awkward, I search for an elegant solution.
This includes the implementation *and* the unit tests.
👇
8️⃣ I perform manual tests after refactoring.
I make sure all the classes are working together 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.
👇
9️⃣ I prepare and review my own PR before sending it.
I hold myself to a relentless standard. I often discard and recreate the PR with even a single nitpick.
In the summary I include relevant Jira or trouble tickets. I document manual testing steps.
👇
🔟 I listen to feedback with objective self criticism.
I make sure I fully understand a teammate's perspective before addressing their comments in a new revision.
Even if their comment is wrong, I understand that it’s likely due to a lack of clarity in my code.
👇
The above steps will improve your code quality and drive down churn on PR’s. This allows you and your team to deliver software faster.
What are some of your tips to improve your own code quality?
• • •
Missing some Tweet in this thread? You can try to
force a refresh
Recently spent a week in Miami at Dev Writer's Retreat. Lead by @swyx (the legend!), ~40 developers came together to grow our writing and blogging skills.
🧵 of a few takeaways:
🔑 Illustrate your ideas
🔑 Leverage constraints for volume
🔑 Build trust with public narratives
🔑 Illustrate your ideas.
As the saying goes, a picture is worth a thousand words. Visuals stick in your brain, and are easier to digest and share.
A lot of code reviewers got immediate, actionable value from this image on Twitter and LinkedIn:
Generally, you shouldn't make product decisions as a consequence of engineering decisions.
Business features and tech stacks don't always integrate smoothly. This creates constraints — and software engineering is about overcoming these constraints with creativity.
Often, creative solutions result in added complexity.
This complexity makes systems more difficult to maintain. Good engineers use abstractions to hide complexity behind a simple interface.
A common mistake of developers new to a "tech lead" role: trying to perform every code review. They're concerned that something will break if they don't.
But reviewing every pull request isn't feasible, and doesn't scale.
What to do instead? Here's what I've learned: 1/8
Enhance your delivery systems outside of code review.
Strengthen your release pipelines with tests, monitoring and rollback. This will help to prevent, detect and mitigate defects. 2/8
Document code review processes.
Team members should be aware of the expected size, scope and structure for each PR. Add automated checks for testing and approval. 3/8
I’ve authored over 550 Pull Requests at Amazon Web Services.
In the past year, I shipped 90% of my PRs in 1 revision. 5 years ago, it often took me 6+ revisions to address peer feedback.
Here’s my step-by-step process to author and ship a quality Pull Request. A thread:
1. I understand why fast PR cycles matter.
PR churn can cause delayed delivery.
It can block my teammates from being effective. If they have to review my PR through several revisions, they have less time to focus on their own tasks.
2. I understand that occasional PR churn is inevitable.
1-revision PRs won't always happen. Humans make mistakes. Peers have unique insights. That’s why code reviews exist.
Particularly, early-career developers at {BigCompany} often need coaching. Even the best programmers.