GIMTEC By Llorenç Muntaner - 🎒 Code Reviews and Micromanagement

Hey 👋,

Have you ever felt micromanaged? What was your experience? I’d love to hear about your experience. So, please reach out by replying to this email.

------------------

A New Team

Imagine you join a company, and it's not your first year as a developer, nor your first job. You feel confident with your coding style and have strong opinions. In the first week, you make your first pull request. One of the other seniors adds a lot of comments in the code review. You agree with some of them, but many of them are about style. You do the changes anyway because it’s your first PR, and you are new to the team.

The following PR is the same: many comments, most of them opinionated, and when you ask why the response is that it's better. After a few weeks, you still get a lot of comments. You don't understand the style of the project and get frustrated with yourself. You start losing confidence in your skills. Is your coding style so bad that it needs so many comments? Why can't you adapt well to the project standards?

At some point, you feel that every single line of code will be evaluated in a way you can't understand. You don’t get to choose how to code; you turn into a machine for making the changes someone asks. You are being micromanaged: none of the code is genuinely your code but someone else's.

Are code reviews supposed to feel like that?

Types of Comments

There are different types of comments in a CR.

- Requirements. Whether the code is completing the task or has the test coverage that the project needs.

- Future errors or problems. Some comments are about the future; for example, will a function become a performance problem, or is a function becoming impossible to read and maintain?

- Standards, conventions, style. Comments about clean code, or what the reviewer considers clean code. Most of these should be caught by a linter, yet some standards are too abstract for a linter rule.

Are all the types of comments equal? Do they all need to be addressed?

- Requirements. Comments about the requirements must be fixed and prevent a PR from merging. Yet, it's essential to understand the limitations of the PR and the task. Not every PR solves all requirements at once. For example, we might decide to code for the happy path first and then, in other PRs, manage the possible errors and edge cases. Still, the comments in this category are mostly objective, not opinions.

- Future errors or problems. If the problem or error is clearly stated, then it’s easily assessed whether it's something that needs to be solved now or later. The changes requested of this type are also primarily objective.

- Standards, conventions, and style. Some standards and conventions are objective rules, such as naming (camel vs snake cases). Yet, many comments in this category are opinionated. For example, why should a function be split in two if it's still readable and maintainable? What is readable and maintainable?

Micromanagement

I set the bar of micromanagement in the last category. In my opinion, CRs start to feel like micromanagement when many comments are about opinionated style.

Yet, most people agree that a project needs a consistent style and should not just be a mix of each developer's preferences. So, how do we ensure that a project stays consistent without micromanaging?

Solution: Document the Project Style

Write down the standards, conventions, and style of the project. Then, if each comment is backed up by a link to the specific entrance in the style book, it becomes an objective comment. Therefore, it doesn't feel like micromanagement.

An example of such a rule is: “Function helpers throw instead of returning wrong or empty data.” This rule is hard to implement in linter. Yet, still objective enough to be easily identified in a CR.

Micromanagement in code reviews happens when the reviewer tries to impose their style on the other developer.

Documenting the coding style conventions turns opinionated comments into objective ones that don't feel personal. Therefore, the developers don’t feel micromanaged. And when a new developer joins the team, the style is easily understood, and the new member will have a better experience and a faster onboarding.

If you like this post, consider sharing it with your friends on twitter or forwarding this email to them 🙈

Don't hesitate to reach out to me if you have any questions or see an error. I highly appreciate it.

And thanks to Sebastià and Michal for reviewing this article 🙏