10 June 2019Comments are off for this post.

How to do code reviews and keep good relationships with co-workers?

Code Review is one of the most important steps in the process of creating clear and high quality software. What do you define as your goal when, as a software developer, you start to verify the code written by other team members? Is it bug hunting? Maybe quality control? Or perhaps learning? Have you ever thought about code review as one of the communication channels and possible ways to build relationships in your work team?

During my conversations with other programmers, especially those who are just starting their programming career, I often hear them talking about stress related to code review. For them, code review is seen as a critique which looks for mistakes in their work. Of course they see the value behind the verification of their code by the people who are not its authors. They also realize that this is a chance for them to learn and improve their qualifications.

At the same time, the code review reminds them of school exams and assessment by other people. These situations are accompanied by the thought that it's not only the code, but also their professional judgment that is being evaluated.

Humanity in code review

Let's be honest - code review is a type of feedback and evaluation. Exactly like in any other type of communication, we have the sender and the receiver. We provide information and we expect some effects. But the effect can not just be well-written code, but also a well-coordinated team satisfied with their work.

How to achieve it? There are 5 simple steps:

Do not talk to the author

When you are directing a message to the author, it becomes more personal. You stop evaluating only the code. You’re starting to judge the person. You point out their mistakes, which they may perceive as undermining their competence. Please note that when you write "typo" it sounds less friendly than writing "person => person". It is better to write "maybe we can change the name of this function" than "change the name of this function".

As I mentioned earlier, one of the main concerns of people asking for a code review is precisely that they are the object of evaluation. And you do this when you are directing a message to the second-person singular - you are talking about the person, not about the code.

Instead of ordering, suggest and request

This is a great way to show your respect to the author of the code. Then you do not assume that your way is better than theirs or their approach is wrong. When your message looks more like a suggestion or question it sounds more tactful, and you and the recipient are then equal partners of the conversation.

"Rename this function" sounds like an order. You become a supervisor, not a partner. You also suggest that the author did something wrong and it is obvious, with no opportunity for any discussion. By changing this comment to the form of the question: "Could we change the name of this function?", you give the author space to answer and justify their choice.

Also, notice that by giving someone an order you take away their autonomy and the authorship of their code. It's not their choice anymore, it's yours. If the author had a reason to write the code in a certain way and would like to defend it, then the conversation may take the form of an argument,

For example, "I do not want to change the name of this function, because it complies with our convention." We will reply to the form of the question "I used this name because in my opinion it complies with our convention. Can you justify your suggestion? "

Give a reason

When you are suggesting a change, also add justification for your proposal. Why should we change anything? Of course, this is not about things like a typo or a missing comma. But if you propose a change in the approach or the solution, please also write why you think it will be better. Is it related to optimization or an accepted convention?

You can also provide links to some articles or documentation. Show that your suggestion is not only your personal opinion. Maybe the author does not know something, maybe he did not take something into account.

Come, call, talk

If you do not understand  or if you have doubts or you suggest a very big change, you don’t have to limit yourself to a comment. If the author is sitting nearby, go to them. If there is a bigger distance between you - call. During a verbal conversation it's easier to explain everything and have a proper conversation. You will have greater confidence that you understand each other and achieve the expected code review effect.

Praise

Have you ever praised anyone during code review? If not, it's really worth trying. For the interns or juniors it would be nice to write at least that their code is getting better and better. You can praise them for an interesting solution or code readability. Think about how you would feel if another team member praised your work. Wouldn’t it be nice to know that you are doing something right?

Our culture is more focused on looking for things to improve. That's why you rarely hear the words of appreciation. And these words are really valuable for teamwork. Hearing words of appreciation for their own efforts can make people feel valuable members of the group, which builds their motivation and loyalty. Believe me - praise is not something difficult or which requires a lot of effort. However, its effects can be amazing.

Recap

Sometimes simple changes can bring  great results. Look at the code review not only as a method to look for errors, but also as another channel of communication with other team members. As with any communication method  our information is essential - it's obvious. But also the manner in which we provide information is very important. It is necessary for effective work and achieving great goals.

Your project deserves significant code
Check what we can do for you!

25 January 2018Comments are off for this post.

Four valuable practices for a better code review

Agile is all about constant improvements. We do retrospectives, we improve our delivery pipelines, we make our work more transparent, and we also do code quality improvements.

The most famous code quality improvement practice is code review. Code review is basically a process of verifying and improving your code quality. It not only helps you make your code better but also helps to educate your teammates. Code reviews can differ in many ways. You can use different tools to share changes and comments or you can just do a face-to-face review and fix everything in real-time.

The pitfalls of code reviews

Bad code reviews can harm your team and lower software quality if you don’t apply them properly. How come? Code review is a communication tool. People are fragile, and people make mistakes. Connect the dots.

If you are too sloppy, you will end up with messy code. If you're too rigid, you will break the team unity and create a stalemate. So, how can you overcome these problems? Here are some tips.

  1. Order your code review goals
  2. Be precise and descriptive
  3. Be motivating and give a good example
  4. Automate as much as possible

1. Order your code review goals

Code review will not fix all code flaws. You need to focus on the most important things.  What is the most valuable outcome of a code review? There is no obvious answer. For instance, a team may value discovering vulnerabilities over improving code readability. If you order these goals, you can focus on important stuff. I suggest writing down all the code review goals, and order and share them across the team. A list of goals may also highlight bad practices the team should abandon or things that should be covered by using another tool other than code review.

Here is the example of an ordered code review goals list:

  • Discover architecture issues
  • Discover performance issues
  • Inspect changed APIs
  • Improve code readability
  • Teach good practices
  • Find naming mistakes
  • Discover bugs
  • Discover vulnerabilities
  • Find typos
  • Find code style issues
  • Laugh over sb else’s code
  • Spend some time on sth else other than programming

You can agree on goals in many different ways. One of them is to create a stylesheet. For instance:

style sheet code review

2. Be precise and descriptive

You find a code issue or you may write a two-word comment to fix it. You may also describe:

  • What is wrong with the code
  • How does it impact the solution
  • How to fix the problem

Which approach is better? The rule of thumb is to answer these three questions. It improves developer experience tremendously. Developer experience is very important, especially if you work in a distributed team.

You could ask how many lines of code you can review on a single day. The intention is obvious: to stay focused. But we are not creating simple procedures these days. Our code is split into functions, classes, modules, and sub-applications. You can set a lines-per-day limit. However, it might prevent you from seeing the bigger picture. I suggest checking your code review goals and decide if a lines-per-day limit makes sense to you. If you run into a code review size problem try to focus on a single goal, starting from the top of the list.

3. Be motivational and give a good example

As I said before, a code review is a communication process. You communicate possible code flaws. Your teammate communicates if he agrees with you or not. Sounds simple, right? Unfortunately, it can get really messy when emotions get in the way. There are a couple of problems.

First of all, software developers are often tied to their solutions. You know this image, right?

richard's software guide

If you try to force your approach, you might end up arguing about spaces vs tabs.  You know you're right. Your colleague knows he's right. You're both wrong. What is the outcome of such an argument? Wasted time and higher tension for sure.

The second thing is that developers try to work like compilers by finding all the mistakes and waiting until your teammate fixes them. It tends to punish minor flaws while ignoring major improvements. How is your teammate suppose to know that he should repeat the very same approach the next time?

The last issue is also connected with the compiler-like code review. If the pull request creator won't fix all the comments, then you won't approve the PR. The code review comments should make the product better. The product gets better when the team gets better. If you push your teammates too hard they will start treating your requests as too rigid and ignore them. There is no point commenting on issues then.

The productive way of doing code reviews allows step-by-step improvements. You want to experience better CRs? Start changing your behaviour first. If you follow the rules below, you will share the positive and professional attitude across your team. The rules are simple:

  • Stop treating code personal.
  • Compliment good solutions.
  • Gradually improve your coworkers' skills & knowledge.

4. Automate as much as possible

A code review requires huge amounts of attention. Fortunately, there are lots of tools that can make your life easier. Many code flaws have been discovered by code analyzers. Some of them point out code style issues, whils others discover possible vulnerabilities or performance issues. Some of them find spelling mistakes and words that are not allowed in your public API code docs.

We can recommend a couple of tools if you work on .NET/JavaScript stack:

  • StyleCop.Analyzers - a tool for C# applications that searches for code style issues
  • ESLint - a tool for JavaScript code that makes JS syntax more strict (e.g. by enforcing semicolons at the end of statements)
  • SonarQube - a continuous integration tool that searches for common code flaws (duplication, vulnerabilities etc.)
  • custom .NET Analyzer- you can write your own .NET code analyzer that works similar to StyleCop.Analyzers but is focused on your custom needs

Remember that automation is more valuable if it works on all developers' machines as well as on the CI server.

Conclusion

There are plenty of ways to improve your code review. However, the most important thing is to be aware of your team and product needs and craft the code review implementation adequately. Always keep in mind that code review is a communication process - the better you explain it, the more value it gives. In order to reduce the scope of conversation, automate validation of repeatable stuff that the team have already agreed on.

OUR OFFICE

Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

OUR OFFICES

POL: Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

ISR: 220 Hertzel Street, 7630003 Israel

COMPANY DATA

Setapp Sp. z o.o.
VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

OUR OFFICES

PL: Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

ISR: 220 Hertzel Street, 7630003 Israel

COMPANY DATA

Setapp Sp. z o.o.

VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

OUR OFFICE

Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

COMPANY DATA

Setapp Sp. z o.o.

VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

 COMPANY DATA

Setapp Sp. z o.o.
VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

OUR OFFICES

POL: Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

ISR: 220 Hertzel Street, 7630003 Israel

COMPANY DATA

Setapp Sp. z o.o.
VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

OUR OFFICES

PL: Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

ISR: 220 Hertzel Street, 7630003 Israel

COMPANY DATA

Setapp Sp. z o.o.

VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

OUR OFFICE

Wojskowa 6, 60-792 Poznań, Poland
+48 506 798 998
office@setapp.pl

COMPANY DATA

Setapp Sp. z o.o.

VAT ID: PL7781465185
REGON: 301183743
KRS: 0000334616

PRIVACY POLICY

klacz
Clutch award badge
topdizajn
svg-image
svg-image
svg-image
svg-image
Instagram Icon
svg-image
svg-image
smart-growth
european-union

©2020 Setapp. All rights reserved.