Writing - Ashwin Gopalsamy

Review Your Own PR First

ashwin@ashwingopalsamy.in (Ashwin Gopalsamy) — Wed, 15 Jan 2025 00:00:00 +0000

Like most developers, I’ve been on both sides of Pull Requests (PRs) – sending them out to colleagues and reviewing others’ code in a sprint to meet deadlines. What I’ve noticed is that the best PRs, the ones that get merged smoothly and with minimal back-and-forth, are the ones where the author has already done a thorough self-review. It’s not just about tidying up code style; it’s about catching design flaws, typos, logic gaps and potential optimisation pitfalls before your teammates do.

In this post, I’d like to walk through why you should review your own PR first and provide some practical steps on how to do it. And hey, I’m writing this because I’ve personally seen the difference it makes while building internet-scale fintech systems for Europe, where a missed detail can lead to big headaches down the line.

What Happens Without Self-Review

Here’s the typical cycle when a PR goes out without self-review. The author pushes, the reviewer catches trivial issues, the author fixes, the reviewer re-reviews, finds more, and the cycle repeats. Three or more round trips before anything substantive gets discussed.

sequenceDiagram participant Author participant Reviewer Author->>Reviewer: Push PR for review Reviewer->>Author: 12 comments (typos, dead code, naming) Author->>Author: Fix trivial issues Author->>Reviewer: Push fixes, re-request review Reviewer->>Author: 5 more comments (missed edge case, style) Author->>Author: Fix again Author->>Reviewer: Push fixes, re-request review Reviewer->>Author: 2 more nits Note over Author,Reviewer: 3+ round trips before merge

1. Why Self-Review Is Critical

a. Saves Time for Everyone

As soon as you open a Pull Request, your teammates set aside time to look at your code. If your PR is full of small mistakes – like typos, unused variables (although unlikely to happen with languages like Go – my primary and favorite programming language), or dead code – reviewers will end up focusing on these easy catches instead of more architectural or design concerns. By cleaning up these obvious issues yourself, you let reviewers zero in on what really matters.

Very early in my career, I once rushed a PR for a critical feature and ended up with a barrage of comments about redundant code and inconsistent naming. About 30 of them. The real logic flaw I introduced got overlooked for a while – until it blew up in staging.

Embarrassing? Yes. It taught me that even a quick self-review can spare everyone a lot of pain later.

b. Improves Your Own Code Quality

Reading your own code diff is like stepping back to observe your painting from a distance. You notice patterns (or anti-patterns) that don’t jump out when you’re in the trenches writing code. Did you name that function well? Is there an awkward datastructure that might be simplified? These insights not only refine your current PR but also shape how you approach coding in the future.

c. Builds Trust and Professionalism

Whether you’re working in a small startup/scaleup (like where I do) or a large enterprise, your PR is a reflection of your work ethic. Taking time to polish your code before asking for a review signals respect for your colleagues’ time. Over multiple sprints, that respect fosters trust and leads to more streamlined team communication.

★

Self-review compounds over time. Reviewers learn that your PRs are clean, so they focus on architecture and design instead of surface issues. This builds a feedback loop where reviews get shorter and more valuable with each sprint.

What Happens With Self-Review

Contrast the earlier cycle with what happens when the author self-reviews before pushing. One round trip, one substantive comment, done.

sequenceDiagram participant Author participant Self as Self-Review participant Reviewer Author->>Self: Read own diff as reviewer Self->>Author: Catch 12 trivial issues locally Author->>Author: Fix naming, dead code, edge cases Author->>Author: Run tests, check linting Author->>Reviewer: Push clean PR for review Reviewer->>Author: 1 substantive design comment Author->>Author: Address feedback Author->>Reviewer: Push final fix Note over Author,Reviewer: 1 round trip to merge

2. How to Perform a Self-Review

a. View the Diff As If You’re Someone Else

I usually open GitHub (GitLab, or Bitbucket in your case), navigate to the Files changed tab, and read every line as though I’m the reviewer. Are the names clear? Is error handling consistent (which is a MUST with Go)? Is there test coverage for every new or changed piece of logic? (You can be conservative, but not here.) By shifting perspective, you’ll catch issues you missed while coding.

In a FinTech context, especially with microservices for accounts, transactions or credit cards, a single nil check might prevent a major production outage. Reading the diff as a reviewer helps me see if I’ve handled edge cases, like a missing value in a 3rd-party API response.

b. Check Commit Messages and Branch Name

Yes, your PR title and description are important, but so are your commit messages. They form a living history of your project. Does it follow (try to) the conventional-commit style? Does each commit represent a logical chunk of work? Or do you see “WIP: fix bug” repeated four times?

Atomic Commits: Make sure each commit fixes or implements exactly one thing.
Good Commit Messages: Follow a structure like fix: handle missing field in transaction flow, rather than “misc changes”.

If you spot multiple fixes or refactors jammed into one commit, consider an interactive rebase to split them up. Similarly, ensure your branch name follows your team’s convention (like JIRA-5678-fix-transaction-timeout) to keep things organized.

c. Document Any Special Considerations

If there’s something non-obvious about your approach – for example, a tricky concurrency hack or a workaround for a known library bug – mention it. Add inline comments in your code or elaborate in your PR description. Your Oncall Engineer will thank you while firefighting a production issue at 3 AM.

✦

If your code references a known bug or limitation, link to any relevant tickets or documentation right in the PR or code comment. Clarity now saves major confusion later. Adding self-review comments on your own PR is also a great way to proactively explain tricky decisions.

d. Validate Tests and Benchmarks

Every new or modified code path should ideally have a test – unit, integration or end-to-end. Quickly run them locally (or rely on CI if it’s robust enough) and check coverage reports if available. Did you add a new database migration script or an additional endpoint? Make sure you’ve tested for both success and failure scenarios.

In a microservice handling accounts or transactions, a single missed test case might break the ledger for an entire day. Tests aren’t just checkboxes; they’re safety nets.

e. Check for Style and Linting

Even small inconsistencies in code style can distract reviewers from more substantial issues. If your team uses linting tools or formatters like golangci-lint , gofumpt or ESLint, run them before you open a PR. Fix any warnings or errors unless they’re truly exceptions to your rule set.

Self-Review Checklist

Before hitting “Request Review”, walk through this checklist. Each “No” is a loop back to fix before pushing.

graph TD Start["Open your PR diff"] --> A{"Diff readable?\nClear naming?"} A -->|Yes| B{"Commit messages\nclear and atomic?"} A -->|No| A1["Fix naming,\nclean up diff"] --> A B -->|Yes| C{"Tests pass?\nCoverage adequate?"} B -->|No| B1["Rewrite commits,\ninteractive rebase"] --> B C -->|Yes| D{"Docs updated?\nPR description clear?"} C -->|No| C1["Add tests,\nfix failures"] --> C D -->|Yes| E{"Linting clean?\nNo warnings?"} D -->|No| D1["Update docs,\nadd PR context"] --> D E -->|Yes| F["Ready for review"] E -->|No| E1["Run linter,\nfix issues"] --> E style F fill:#10b981,color:#fff,stroke:none style Start fill:#64748b,color:#fff,stroke:none style A fill:#6366f1,color:#fff,stroke:none style B fill:#6366f1,color:#fff,stroke:none style C fill:#6366f1,color:#fff,stroke:none style D fill:#6366f1,color:#fff,stroke:none style E fill:#6366f1,color:#fff,stroke:none style A1 fill:#f59e0b,color:#fff,stroke:none style B1 fill:#f59e0b,color:#fff,stroke:none style C1 fill:#f59e0b,color:#fff,stroke:none style D1 fill:#f59e0b,color:#fff,stroke:none style E1 fill:#f59e0b,color:#fff,stroke:none

3. Common Pitfalls (And How to Avoid Them)

Too Large PRs
- Solution: If you find your PR has grown too large, consider breaking it into smaller chunks. Maybe the database schema migration script can (in ideal cases – SHOULD) be a separate PR.
Neglecting Documentation
- Solution: If your changes include a new API endpoint or config file, update the README or relevant docs. Reviewing your own PR is a great time to spot missing documentation.
Lack of Context in the PR Description
- Solution: Summarize what changed, why it changed, and any impacts on the system. This ensures the reviewers understand the context from the get-go.
- Another one: I have a habit of adding PR comments pointing to my code explaining tricky bits or why I made a certain decision. It helps me think things through and makes it easier for reviewers to quickly grasp the rationale behind my decision later on.
Forgetting to Rebase or Merge Main
- Solution: Before you finalize your PR, pull in the latest changes from main or develop (depending on your workflow). Fix any merge conflicts now rather than letting your reviewer handle them.

4. The Ripple Effect of a Good Self-Review

a. Faster Approvals

If your PR is clean and well-structured, your reviewers won’t have to spend time on trivial comments or guess your intentions. This leads to a more constructive review session where you can focus on potential design improvements and edge cases, ultimately speeding up merges.

b. Better Team Morale

Pull requests often come with a bit of stress; nobody wants that dreaded “Can you fix these 17 things?” comment. A well-reviewed PR shows you respect the review process, which makes your teammates more eager to review your work. This mutual respect boosts morale and reduces the friction sometimes found in code review cycles.

c. Stronger Codebase for Production-Grade Systems

In FinTech or any high-stakes industry, code reliability is paramount. Errors can be costly – financially and reputationally. By catching small bugs and questionable logic early, you reduce the risk of these issues making their way to production.

I remember we once traced a subtle floating-point rounding bug that only appeared in large batch transactions. Had I done a thorough self-review, I think I might’ve caught it. Instead, we found out during a production spike, leading to a hotfix scenario.

5. Final Thoughts

PR reviews are not just a box to check or to rely on others to correct our mistakes; they’re a vital step in producing quality, maintainable software. By reviewing your own PR first – treating it like someone else’s code – you’ll create a better experience for both yourself and your reviewers. Think of it as a courtesy that doubles as a code-quality accelerator.

✦

The simplest habit that pays the biggest dividends: before clicking “Request Review”, open the Files changed tab and read every line as if a colleague wrote it. If something makes you pause, fix it. Your reviewers will notice the difference within one sprint.

Thanks for reading. If you found this helpful, feel free to leave a comment or share your own stories. I’d love to hear how self-review has impacted your codebase or your team’s productivity.

Happy Coding – and Happy Reviewing.

Git Practices for Production Codebases

ashwin@ashwingopalsamy.in (Ashwin Gopalsamy) — Thu, 14 Nov 2024 00:00:00 +0000

Git is the backbone of every software project. Whether you’re squashing a bug, developing a feature, or tracing a production issue, Git quietly keeps track of everything. But let’s face it – Git can be as much of a headache as it is a lifesaver, especially if the history is messy or branches are all over the place.

Working in highly critical, production-grade FinTech systems, I’ve learned that Git isn’t just a tool – it’s a shared language and a safety net. In environments where even minor mistakes can ripple across services, impacting compliance, customers, and trust, clean Git workflows become non-negotiable. Having managed core banking systems within this context, I always strive for structured commits, well-defined branches, and clear pull requests (PRs) to maintain the integrity of the codebase.

✎

In FinTech and regulated environments, every change must be auditable and traceable. Clean Git practices are not just about developer productivity – they are a compliance requirement. Structured commit histories, well-scoped branches, and documented PRs form the paper trail that auditors and incident responders rely on.

Here’s a guide to Git best practices I almost follow (and aspire to), aimed at keeping repositories clean, collaborative, and resilient in the face of production challenges.

Commits: The Backbone of Your Codebase

A Git history should feel like a well-documented timeline of your project’s development, not a chaotic log of random changes. In highly critical environments, where changes must be audited and traceable, well-structured commits are crucial.

1. Write Atomic Commits

An atomic commit focuses on one thing – fixing a bug, adding a feature, or refactoring code. This ensures every commit is clear, self-contained, and easy to understand. It also makes debugging and rollbacks safer.

Example:

Good:

feat: add endpoint for retrieving user account balances
fix: resolve timeout issue in interest calculation

Bad:

misc: fix bugs and add features

In early career, I’ve learned (the hard way) that bundling unrelated changes into a single commit creates confusion and risks during rollbacks, especially when a quick fix is required for production.

2. Use Descriptive Commit Messages

Your commit message should explain what changed and, if needed, why. Following a consistent format helps everyone on the team (including your future self) understand what’s going on.

<type>(<scope>): <subject>
<BLANK LINE>
<body (optional)>

Examples:

fix(auth): resolve token expiration handling for API calls
feat(worker): implement batch processing for interest accrual

These messages don’t just help during reviews – they’re lifesavers when digging through logs or debugging an issue six months down the line.

✦

The Conventional Commits Specification formalizes this format. It pairs well with tools like commitlint and enables automatic changelog generation, semantic versioning, and structured release notes from your commit history alone.

graph LR A["feat(parser): add bitmap validation"] A --> B["type
feat"] A --> C["scope
parser"] A --> D["description
add bitmap validation"] style A fill:#64748b,color:#fff,stroke:none style B fill:#10b981,color:#fff,stroke:none style C fill:#6366f1,color:#fff,stroke:none style D fill:#f59e0b,color:#fff,stroke:none

3. Automate Commit Linting

No matter how disciplined we are, it’s easy to slip up. That’s where Commitlint comes in. It’s a lightweight tool that ensures your commit messages follow a defined convention, like Conventional Commits.

Tools for Commitlint:

Commitlint by Conventional-Changelog : This is one of the most popular Commitlint tools. It’s simple, extensible, and works seamlessly with Husky to enforce commit message rules during pre-commit or pre-push hooks.
Commitlint by ConventionalCommit : Written in Golang, this lightweight Commitlint tool is fast and easy to set up for smaller teams or those already using Go. It’s perfect if you prefer tools that feel native to your tech stack. My personal favorite.
Conventional Commits Specification A useful guide to the conventions enforced by these tools.

Setting up Commitlint is straightforward, simple and easy. The long-term benefits – clear commit messages, consistent history – are well worth the effort.

Branches: Organized and Traceable

In highly critical systems, branch organization is non-negotiable. It’s not just about avoiding confusion – it’s about making sure work can be traced back to its purpose, especially in microservices architectures where each service lives in its own repository.

1. Follow a Consistent Naming Convention

A good branch name starts with the task or issue identifier, making it easy to see what the branch is for. I always use this format:

Format:

<JIRA-ticket-ID>-<type>-<short-description>

Examples:

JIRA-5678-fix-transaction-timeout
JIRA-1234-feature-add-batch-processing

This convention has saved me – and my team – countless hours when tracking work across multiple repositories.

2. Keep Branches Short-Lived

The longer a branch stays open, the more likely it is to diverge from the base branch. I aim to merge branches into main or develop frequently, keeping integration smooth and reducing conflicts.

3. Rebase for a Clean History

Rebasing instead of merging keeps your branch history linear, which is much easier to follow during debugging or reviews.

Example Workflow:

git checkout JIRA-5678-fix-transaction-timeout
git pull --rebase origin main

Rebasing has saved me from so many messy histories, but I’m always careful not to rebase shared branches like main.

★

Rebasing rewrites commit hashes, so it should only be used on local or feature branches. The payoff is a linear history that reads like a narrative rather than a tangled graph. During incident investigations, a linear git log lets you bisect and isolate the offending change in seconds rather than minutes.

gitGraph commit id: "init" commit id: "v1.0" branch JIRA-5678-fix-timeout commit id: "add retry logic" commit id: "handle edge case" commit id: "add tests" checkout main commit id: "hotfix: logging" checkout JIRA-5678-fix-timeout merge main id: "rebase onto main" type: HIGHLIGHT checkout main merge JIRA-5678-fix-timeout id: "squash merge" type: HIGHLIGHT commit id: "v1.1"

Pull Requests: Your Code Documentation

Pull requests are where collaboration happens. In highly critical systems, they also serve as an essential checkpoint to catch mistakes before they make it to production.

1. Use Clear and Structured PR Titles

A PR title should be concise but informative. I use this format to keep things consistent and easily traceable:

[JIRA-ticket-ID] <Type>: <Short Description>

Examples:

[JIRA-5678] Fix: Handle transaction timeout edge cases
[JIRA-1234] Feature: Add bulk processing for transactions

2. Write Descriptive PR Descriptions

A good PR description provides enough context to help reviewers understand what’s changing and why. I try to answer three key questions:

References and Documentation
What changed?
Why was this change made?
Does it introduce any risks or side effects?

### What
Added a batch endpoint for processing transaction summaries.

### Why
This improves efficiency for bulk transaction reconciliation.

### Impact
- Adds a new API endpoint.
- No breaking changes.
- Includes unit and integration tests.

3. Keep PRs Small and Focused

Large PRs are overwhelming to review and prone to mistakes. I aim to keep PRs focused on a single feature, bug, or task to make reviews faster and more effective. It is absolutely okay to have couple of PRs for few critical implementations separated by small subtasks/milestones, in my opinion.

Example: Schema migration as a separate Pull Request.

4. Use Checklists and Labels

Checklists ensure that every step is complete before merging:

Unit tests added
Integration tests verified
Documentation updated

Labels is such an under-rated feature, which I regularly use. Labels like feature, fix, or hotfix also help prioritize reviews and are easy to filter out and dig back when required.

graph LR A["Branch Created"] --> B["Commits"] B --> C["Self-Review"] C --> D["PR Opened"] D --> E["CI Passes"] E --> F["Code Review"] F --> G["Approved"] G --> H["Squash Merge"] H --> I["Branch Deleted"] style A fill:#64748b,color:#fff,stroke:none style B fill:#64748b,color:#fff,stroke:none style C fill:#64748b,color:#fff,stroke:none style D fill:#64748b,color:#fff,stroke:none style E fill:#10b981,color:#fff,stroke:none style F fill:#64748b,color:#fff,stroke:none style G fill:#10b981,color:#fff,stroke:none style H fill:#10b981,color:#fff,stroke:none style I fill:#64748b,color:#fff,stroke:none

Why These Practices Matter

In highly critical, production-grade FinTech systems, precision isn’t optional. I’ve seen how poor Git practices can snowball into major issues – long debugging sessions, delayed releases, or even customer-facing outages. Clean commits, structured branches, and clear PRs aren’t just best practices – they’re safeguards for the stability and trustworthiness of the systems we build.

By following these practices:

Debugging in production becomes faster and more efficient.
Collaboration is smoother because everything is easy to trace.
Compliance and audits are simpler, with clear histories and well-documented changes.

If you’ve got your own favorite tools or Git horror stories, let’s swap notes. The best practices we share today could save someone a lot of time (and stress) tomorrow.