Shortly about.. criticism, code reviews, comments

techie_ania profile image Ania ・2 min read

You wrote some code, you're about to push.. wait a sec, please.

Working together

Most of the time developers work in teams. There is a lot of collaboration, hopefully, appreciation of the effort and, also hopefully, criticism. Yes, criticism. It should NOT be about making comments on someone's ability to do their job. It should NOT be directed at a person at all. It's about the shared code, making sure everyone understands how to work with it, how to make modifications when needed. It's about the trust that the code will do its job and not fail easily.

Hello, my name is...

When you name your variables, files, write commit messages, name tests, state your point in a meeting, writing a bug report... think about this: you are working in a team and the goal is for what you create to work in a bigger context.

Once you write your code, take a break, then read through it without going through how exactly it works.. think about:

  • Would it make sense for other people in your team? You know your colleagues, think of what kind of changes they usually ask for, what are their usual comments and aim for cleaning up the code in such a way that it will not require updates you know they will request.
  • Are the variables, functions, class names, etc. clear and accurate? Are you naming things by what they are/do?
  • Are you following conventions the team agreed to?
  • Think of what you would be commenting on when reading through another person's code.
  • Be critical of your own work.

Let's all be nice

As for commenting on other people's work, stay away from a passive-aggressive tone, which creeps in at times. Read your comments before submitting them. Be clear, be concise, be polite. Write about the changes in code you propose and explain why, shortly. Be open to discussion about your comments.

It's not about you

One thing I want to make clear. None of the criticism coming from others or yourself(!) is to make you feel bad, it is about getting the code in a state where it will work well for the client, the end-users, and make your colleagues happy and efficient when working with it. They WILL appreciate it and you for it.

Even if you feel a particular comment is directed at you, think if it should. Then ignore the personal part of it, think if there is something actionable and useful about it. Use that part. Only then you can decide to ask politely for the person to comment on the code, not you. But that's a topic for another time...

Author's note:

Let's practice positive critic here :)

I gave myself about 30 minutes to write it and then another few minutes to correct it, so that I don't keep procrastinating on my first post!


Editor guide