Forem: Michaela Greiler

We are 10x engineers

Michaela Greiler — Thu, 18 Jul 2019 11:06:03 +0000

10x engineers come in all shapes and sizes. They have different background screen colors and different skin colors. Different tastes and interests. And, they have different strengths and weaknesses.

A few weeks ago there was a heated Twitter discussion about how to spot a 10x engineer.

And Twitter was furious. Why?

Well, I believe mostly because of the characteristics that described this 10x engineer. It said a 10x engineer hates meetings, has a dark laptop screen background, works fueled by caffeine without breaks, is a full-stack engineer that seldom works on the UI, does not mentor others as mentoring slows down, does not document the code, and so on.

Here is the original tweet:

10x engineers

Founders if you ever come across this rare breed of engineers, grab them. If you have a 10x engineer as part of your first few engineers, you increase the odds of your startup success significantly.

OK, here is a tough question.

How do you spot a 10x engineer?

— Shekhar Kirani (@skirani) July 11, 2019

Stereotypical description and unhealthy advice

The description was stereotypical and had little to nothing to do with the abilities of an engineer. A lot of the advice, such as “a 10x engineer knows every line of the code that has gone in production” isn’t solid advice either.

For example, if that one is true, you probably have a tiny code base and in addition, a person that easily creates a bottleneck in your pipeline. But, I don’t want to discuss each of the statements. I want to look at the overall message of this thread.

Excluding a large part of the engineering population

One of the problems with this thread is that the description of such a 10x engineer excludes a large part of the engineering population. The bottom line, if you do not fit this narrow (and often ludicrous) description, you aren’t a top-notch developer. But engineers and also great ones come in all shapes and sizes. They have different colors of laptop screens, different skin colors, different hair, and different tastes and interest. Some even drink tea or water instead of coffee

Don’t use genius as an excuse to behave like a jerk

But there was something else going on. The thread described a person that isn’t a ~~good~~ team player. And as many of us have already suffered from working with an anti-social person whose genius is used as an excuse to just behave like a jerk, I understand people did not take this tweet well.

It created this image of a superior person that supposedly knows everything better than her or his peers, and finds helping others a waste of time. And even though, for some engineers it might be indeed hard to socialize, mentor and work with others, we should detain ourselves from glorifying toxic behavior. We better use our time to think about how we can create a welcoming environment for all people, so they can grow and learn together.

Very fitting to this aspect of the discussion is this article that talks about how firing a 10x engineer actually saved a whole company.

But there was much more going on under the radar.

What exactly is a 10x engineer?

I think another aspect of why people were so furious is because nobody knows what a 10x engineer is. Supposedly, it is an engineer that is 10x better, faster or more productive than the rest of the engineers. But, does such an engineer even exist? And how would we measure those 10x achievements?

Well, the main problem is exactly how we measure 10x. Depending on how broad or narrow we scope the measurement we get different results.

Different in terms of who is how productive, but also different in terms of how valid or trustworthy this measurement is. The narrower the scope of the task that we measure, the more “solid” the comparison. But on the other hand, the more narrow the task, the more useless becomes the measurement.

Don’t compare apples with oranges

To give you an example, if we try to measure the work of a software engineer, we are not able to do so in a meaningful way. The range of tasks and the possibilities to measure the outcome (quality, speed, impact) is just too broad. It isn’t for no reason that we can’t and should not assess productivity by a single metric.

So, we must limit ourselves to a tiny unit, of say solving one specific problem, in a specific language, for example reversing a linked-list in C. Then, we might assess the performance of people by looking at the time to completion. But, what about the complexity of the solution? What about the readability of their solution?

Well, we could come up with measurements for each of those aspects, but the better question to ask is what does that tell us?

Some people are much better at a certain “thing” than others

In The Mythical 10x Programmer, you find a discussion of such a comparison. It nicely shows that the unit of measurement has to be indeed very narrow to allow us to compare the outcome. It also shows that there are 6x to 11x differences in how people solve one specific task. That’s not a surprise to me. Probably also not to you?!

But, again, what does that tell us?

My conclusion of these results differs from the conclusion of the original researchers.

For me, it simply means that one person can be much better at some specific things than another person . And that’s exactly why we must strive for an inclusive and diverse team. Great engineers come in all shapes and sizes. They also come with a lot of different strengths and weaknesses.

This “thing” that they are really good at might be reversing a linked list in C. Or maybe they excel when designing an architecture for a software system. But, it could also be that they are excellent in explaining complex problems to a non-technical audience. This “thing” could be that they are great listeners and know about problems customers or teammates experience before anybody else.

Let’s get a diverse team to be the best at a diverse set of “things”

Our work as software engineers is manifold, and to really succeed we need a diverse set of people with diverse skill sets, backgrounds, and experiences.

And we need environments where people can be their best selves and strive in the environments we create.

So, we shouldn’t focus on spotting that one genius engineer, as we do not have that one specific problem to solve.

We better use our time and resources to think about how we can enable all kinds of people to excel at what they are great at. Because even the best engineer can’t substitute a great team.

So, let’s focus on creating a 10x team! Or to create a 10x more inclusive environment. Well, let’s start by being 10x friendlier and more supportive of each other.

If you like this article, consider signing up for my mailing list, so I can notify you when I publish something new. I also prepared an exclusive 20-page Code Review e-Book as a thank you for my email subscribers.

My newest project is a podcast called Software Engineering Unlocked. Here I talk with experienced developers from different companies, with different backgrounds and experiences on how they develop software. Sign-up today.

The post We are 10x engineers appeared first on Doctor McKayla.

Proven Code Review Best Practices from Microsoft

Michaela Greiler — Thu, 02 May 2019 13:01:47 +0000

What are the code review best practices companies such as Microsoft follow to ensure great code review feedback? How do you stay productive while doing code reviews? Learn proven code review best practices from Microsoft in this article.

The benefits of code reviews rise and fall with the value of the code review feedback. If done correctly, code reviews can help to ensure a high-quality code base. However, if teams are not aware of and do not follow code review best practices, developers may experience several code review pitfalls. In the worst case, reviewing code can slow your team down.

I have been researching and working with teams at Microsoft for several years. Through several large scale-studies, we discovered a number of code review best practices that help teams stay productive and boost their code review value. But first, let’s start at the beginning. What does code review look like?

A typical code review process

A typical tool-based code review process starts when the engineer prepares the code for review. Then, she selects relevant reviewers for the code change. The reviewers are notified and give feedback on the code. The code review author works on the feedback until all parties are satisfied. Then, the code is checked into the common code base.

A typical tool-based code review

To ensure that this process is smooth and does not become a nightmare, it is important to understand code review pitfalls and which code review best practices you can follow to overcome those.

The main code review pitfalls are:

not getting useful feedback,
not having enough time to do code reviews,
code reviews taking too long causing long waiting times.

The code review best practices I present below help counteract those pitfalls, by making the job of the reviewers as easy as possible. They also help the reviewer to focus on providing valuable feedback.

Code review best practices for code authors

In a code review, there are two different stakeholders: the code author who asks for feedback and the code reviewers, who look through the code change and provide the feedback. As a code review starts with the author, I explain the code review best practices for code authors first.

Check out the VIP Code Review e-Book I prepared for my subscribers.

For my e-mail subscribers, I prepared an exclusive code review e-book including a checklist with all code review best practices. I also added additional bonus insights. You can request the Code Review e-Book here.

Read through the change carefully

The first code review best practice is to read carefully through the code change before submitting the code for review. There is nothing worse than asking several developers to look through the code and give feedback on issues you could have fixed yourself.

This wastes everyone’s time and it might make you look bad. For future code reviews, developers may also be reluctant to review your code.

So, ensure you use a code review tool or a diff tool that can highlight what changed between this and the previous version. Because the code is presented in a different way and changed code passages are highlighted, it makes it easier for you to review your code yourself before sending it out.

Often you will see changes that you actually forgot you made or missing issues highlighted you should fix before asking somebody to review.

The best time to fix issues is before the code is sent out for review.

Thoroughly look through your code before submitting for review
Photo by Marten Newhall on Unsplash

The best time to fix issues is before the code is sent out for review. Click To Tweet

Aim for small, incremental changes

As a developer, you should always strive for small, incremental and coherent changes. This best practice helps when working with code revision tools, such as git or SVN.

Small, incremental code changes are also a crucial code review best practice as other developers must be able to understand your code change in a small amount of time.

10 lines of code = 10 issues.

500 lines of code = “looks fine.”

Code reviews.

— I Am Devloper (@iamdevloper) November 5, 2013

If several changes with different purpose happen within one code review the task of code reviewing becomes more difficult. This also decreases the ability of code reviewers to spot problems with the code. In several studies, we see that the value of the code review feedback decreases with the size of the change under review.

On the other hand, you also want to make sure the changes are coherent. Rarely code changes are too small to be sent out. It happens, but, not that often.

The quality and value of code review feedback decrease with the size of the change. Click To Tweet

Cluster related changes

Another code review best practice is to cluster related code changed. Imagine you plan to add some new functionality, fix a bug in another function, and refactor a class. Then, each of those changes should be a separate code review. This way, you ensure the purpose of the code change is clear to the reviewers. A clear purpose makes the reviewing job much easier and increases the feedback value.

Describe the purpose and motivation of the change

One way to make sure you invest your time right during code review preparation is to write a description of what this code change is all about. With a small note, you help the code reviewers to understand the purpose of the code change and also why you changed it. This code review best practice speeds up code review time, increases the quality and value of the feedback, and improves code review participation rates.

Code reviewing isn’t a puzzle. Help reviewers focus on key issues by describing the code change.
Photo by Hans-Peter Gauster on Unsplash

Code reviewing isn't a puzzle. Help reviewers focus on key issues by describing the code change. Click To Tweet

Interestingly, in our studies, we observed that developers really appreciate code change description. They actually wish that more people would write descriptions. On the other hand, we saw that the same developers did not always include descriptions themselves.

One reason for this is that when you write the code yourself, you are so involved with the code that you think it is self-explanatory. Fact is, it is not.

And if you do not help the reviewers to understand the code, they will not be able to provide valuable feedback.

So, write the note, even if it just says: “Updated the API endpoint to be compliant with security regulations”.

How much easier did the job of reviewing the code just get with this note? Remember, code reviewing isn’t a puzzle!

Even if the code change seems trivial to you, add a description, so reviewers know what to expect. Click To Tweet

Run tests before submitting a code review

Yes, take the time to run the tests for your code change. Testing isn’t only a best engineering practice, but it’s also a code review best practice. Because testing your code ensures that the code actually works before you ask for feedback.

In addition, it shows that you respect the time of the code reviewers. It is not only embarrassing to send out code that obviously (as the tests show) is not working as expected, it also kills everyone’s productivity. So, run the tests first!

Automate what can be automated

As one of the main pitfalls for code reviews is taking too long, you better follow the code review practices of automating what can be automated.

Use style checkers, syntax checkers and other automated tools like static analysis tools to help improve the code. This way, you make sure that code reviewers can really concentrate on giving valuable feedback and do not need to use their time to comment on issues that can be found automatically.

Skip unnecessary reviews

You read that right. Some reviews can be skipped. Obviously, it depends on your organizational policies, but if they permit it, you might consider skipping code reviews.

But stop before heading out and telling your team you need no code reviews anymore. Skipping code reviews is only advisable for trivial changes that do not change the logic such as commenting, formatting issues, renaming of local variable or stylistic fixes.

Skipping unnecessary code reviews boosts your productivity. Click To Tweet

Do not select too many reviewers

You should select the right number of reviewers for your code change. If now numbers above 4 people come to your mind, I’d like you to stop right there. Because adding too many developers on code reviews does more harm than good.

One problem is that if you add too many developers, each one of them feels less responsible to give feedback. Another issue is that adding more people than necessary decreases your team’s productivity.

Some studies suggest the code review best practice of adding only two active reviewers.

For some code changes, you want additional experts like security experts or developers from other teams to look through the code. But, more often than not, two active reviewers are just fine.

Many code review tools allow notifying developers without making them mandatory reviewers. This ensures that they stay in the loop and are aware of what is happening, but removes the obligation for them to comment on your code.

Add experienced reviewers to get insightful feedback

Studies have shown that the most insightful feedback comes from reviewers that have worked on the code you are going to change before. They are the ones that give the most insightful feedback.

How often a reviewer has already reviewed code influences the ability to give useful feedback. Similar, experienced and senior developers tend to give better code review feedback.

But, be mindful about the workload of senior engineers, as they tend to be added as reviewers a lot.

Developers that changed or reviewed pieces of the code before, give the most valuable code review feedback. Click To Tweet

Add junior developers to let them learn

One of the code review goals is training and learning, so do not forget to include junior developers. Consider adding reviewers that are not familiar with the code base, but that would benefit from the knowledge to allow knowledge dissemination.

Notify people that benefit from this review

For some people, like project managers or team leads, receiving notification about code reviews (without being actually required to do the code review) is beneficial. But, you have to take a conscious decision on whom you gonna notify. Not everybody really cares or should care about your code review.

Don’t notify too many people

Do not add everybody on the notification list. Only add people who actually benefit from the information that a code review is in the process.

I have seen teams, where each team member was added to each of the code review of the extended team by default (+70 people). This practice is like adding nobody to the list. Or in the worst case, you have several of your engineers spending their time looking through hundreds of code reviews to figure out if it’s relevant for them.

Give reviewers a heads-up before the review

A really effective code review best practice is to let your co-workers know ahead of time that they will receive a code review soon. This code review best practice reduces turn-around times substantially.

So, let them know a code review is coming their way as soon as possible.

Giving people a heads-up that a code review is on its way can speed up review time. Click To Tweet

Be open to suggested changes

Receiving unexpected comments or feedback might make you tense and defensive. Try to prepare yourself mentally and work on your ability to be open to suggestions and different viewpoints. Always start with the assumption that the reviewer had the best intention.

Don’t be defensive if confronted with unexpected feedback.
Photo by Sweet Ice Cream Photography on Unsplash

If some feedback made you uncomfortable try to sort things out as soon as possible. Sometimes it is a good idea to have more personal face-to-face conversations to resolve some issues.

Show respect and gratitude to the reviewers

Code reviews rise and fall with the team’s feedback culture. As a code author, show gratitude and value the received feedback. Make sure to carefully consider the reviewers’ feedback and communicate throughout the feedback cycle.

Tell the reviewers which actions you took and which decisions you made because of the received feedback in a respectful manner.

Code review rises and falls with the quality of the team's feedback culture. Click To Tweet

But, creating a great feedback culture is a two-way street. Naturally, code reviewers influence the culture a lot. So let us look closely at the code review best practices for code reviewers.

Code Review Best Practices for Code Reviewers

Being asked to give feedback on a code review is an honor, so you want to make sure you know how to give valuable code review feedback.

During code reviews, you can not only demonstrate your skills and knowledge but also mentor other developers and contribute to the team’s success. Nothing worth than investing time in code reviews and not getting valuable feedback.

Give respectful and constructive feedback

Even though it reads like a no-brainer, code reviews do put the code author in a vulnerable position, so you must be considerate of that.

Your job is it to give constructive and valuable feedback but also to do so in a respectful manner.

Especially using code review tooling, please reflect on how and what kind of feedback you give. It is just so easy to hurt someone feelings – especially in written form. Too often time pressure might make you give a sloppy answer that can be misinterpreted.

Go and talk in person if necessary

Code review tools and chat-tools allow us to communicate with our peers in an asynchronous and effortless way. But, there are quite a few situations where a proper human interaction, either face to face or via voice/video cannot be bet.

Complex issues, for example, can be much more efficient and positively resolved once you hop over to your colleague or call her and discuss it personally. The same holds true for contentious issues or sensitive matters.

Maybe it is a better strategy to write a private email or seek a personal discussion with the code author if you think you might hurt some feelings are make the engineer lose the face. So, whenever you face a complex issue or might hurt some feelings, rethink your communication channels and act accordingly.

Ensure traceability for decisions

Even though less traceable conversations, such as face to face or video calls can make a big difference for team dynamics, it is important to document the discussion. Especially the code review outcome should be tracked for future reference by using traceable tools such as the code review tool.

The code review tool is the right communication channel for all simple matters, as it allows the whole team to follow along, and enables to look-up decisions and understand code development after the fact.

Leaving traces about your decisions and changes helps to understand code evolvement
Photo by Marten Bjork on Unsplash

Always explain why you rejected a change

Let’s be honest. Having a code change rejected isn’t something the code author will enjoy. So, it is important that you are thoughtful and explain your rejection in a polite, constructive and friendly way.

Explaining the reasons behind your decision does not only help the code author to learn and grow but also helps the author to understand your viewpoint. It also promotes an ongoing dialog with the author.

Tell the code author exactly what she has to do to get the change accepted.

If you have to reject a code change, explain exactly what has to happen that the change can be approved. Click To Tweet

Code review best practices for boosting productivity

Some of the biggest challenges during code reviews, for both the code author and the code reviewer are time constraints.

As a reviewer, you might find it challenging to take time out of your daily tasks to review the code of your peers. But, code reviews can be very beneficial to you and the team if done in the right way.

Integrate code review into your daily routine

Structure your day-to-day business in a way that you set dedicated time aside just for doing code reviews. For example, plan to work on code reviews every day from 11 to 12 AM.

This way you make sure you can account the time for code reviews, and also make it an anticipated activity for you and your team. This schedule will come in handy every time you have a reflection on your work progress or an evaluation of your work.

Reduce task switching as it kills productivity

Switching from one task to another is costly. Knowing you do not stop whatever you do every time a code review comes along your way ensures you can work more focused.

Which time slots work depends on your workload, the number of code reviews you have to perform as well as on the time those reviews normally come in. In some settings, your team benefits from two (shorter) scheduled reviewing times, such as in the morning and before you leave the office. This way, your peers do not have to wait for your feedback too long.

Task switching kills productivity
Photo by Tim Gouw on Unsplash

Task switching kills productivity. So have dedicated code review times. #codereview Click To Tweet

Give feedback in a timely manner

It is not advisable to jump right into a code review, whenever the notifications pop up, because of context switching costs. Still, it has several advantages for you and the code author to review the code in a timely matter.

Giving feedback as soon as possible ensures that the code author is not blocked by waiting for feedback. Also, if the author has to wait too long, it becomes harder for her or him to remember the changes and incorporate the feedback. Remember long waiting times are a number one code review pitfall.

Being one of the first reviewers (especially if there are quite a few) also ensures your effort looking through the code actually adds value. If you are the fifth person inspecting the code, chances are you are not going to add new insights anymore. If that happens frequently, you should implement the code review best practice for selecting fewer reviewers.

Review frequently not in a big bang fashion

Research shows that you can give better quality feedback if you review frequently and therefore less changes at a time. That means that you do not wait until several code reviews pile up to look through them in one go. Instead, you stick to your schedule and review one code review (or even parts of one if it is a larger code review) at a time.

If code reviews are generally too large and take too long, you can suggest the code review best practices for small, incremental and coherent changes to the code review authors.

Give better quality feedback to code reviews by not letting them pile up. Click To Tweet

Focus on core issues, less nit-picking

Your goal as a reviewer should be to help with core issues, such as bugs, architectural problems, structural problems or problems that will lead to maintainability issues.

Obviously, if you see typos, badly named variables or styling issues, you might also point that out. Still, this is not your main tasks and, understandably, over discussing minor issues isn’t valuable to code authors.

Use a review checklists

Another code review best practice is to use a systematic approach for code reviews. A code review checklist can speed-up and improve your code review performance. Instead of making one from scratch, download a ready-made list and customize it to fit your team’s practices and your needs. Be sure to look for a checklist that is tailored towards your technology stack.

Code review best practices checklist

Now you know all the code review best practices to make the most out of code reviews. If you enjoyed this post, consider subscribing to my email list.

I prepared an exclusive Code Review e-Book for my e-mail subscribers to help you remember the code review best practices. I also added other great insights and summaries about code reviews. Get the 12-page insights to code reviews now. Not a subscriber yet? Just sign-up.

Exclusive Code Review Best Practice e-Book for my subscribers.

Coming next: Code reviewers tradeoffs and organizational issues

In the next blog post, I want to share with you which tradeoffs you have to keep in mind when doing code reviews. For example, do you favor review speed or review rigor? In addition, I also show you which best practices teams and organizations should follow to use get the most out of code reviews.

Never miss a post: Sign-up to my mailing list

To not miss my next post in this code review blog post series, make sure you subscribe to my mailing list. This way, I will notify you as soon as the next blog post is up.

The post Proven Code Review Best Practices appeared first on Doctor McKayla.

What are the most gruesome code review pitfalls you encountered?

Michaela Greiler — Wed, 10 Apr 2019 08:32:45 +0000

I surveyed more than 900 engineers on their code review pitfalls. People mainly complain about time constraints and problems understanding the code change.

What are the most painful pitfalls you experienced and do you have ever had a horrendous experience with code reviews?

How to avoid Code review pitfalls that slow your productivity down!

Michaela Greiler — Sat, 06 Apr 2019 18:36:01 +0000

Code reviewing is an engineering practice used by many high performing teams. And even though this software practice has many advantages, teams doing code reviews also encounter quite a few code review pitfalls.

In this article, I explain the main code review pitfalls you should be aware of to ensure code reviewing does not slow your team down. Knowing which pitfalls and problems arise, can help you to ensure a productive and effective code review experience. Those findings are based on a survey we conducted at Microsoft with over 900 participants.

A typical code review process

A typical tool-based code review process looks roughly like this: Once the developer has finished a piece of code, she prepares the code for being submitted for review. Then, she selects reviewers who are notified about the review. The reviewers then review the code and give comments. The author of the code works on those comments and improves and changes the code accordingly. Once everybody is satisfied or an agreement is reached, the code can be checked into the code base.

In another post, I described how a typical code review process looks like at Microsoft.

For my e-mail subscribers, I prepared an exclusive code review e-book including a checklist with all code review best practices. I also added additional bonus insights. You can request the Code Review e-Book here.

Check out the VIP Code Review e-Book I prepared for my subscribers.

Code reviewing isn’t always a smooth process

These steps read like a smooth process. But, like everything, in practice, things tend to be more complicated than anticipated. During the code review process, there are quite a few pitfalls that can reduce the positive experience with code reviews for the whole team. If not done correctly, code reviewing can also take its tolls on the whole team’s productivity. So, let’s have a look at the difficulties and pitfalls of code reviews.

The two main types of code review pitfalls are about the time spent on code reviews, and the value code reviews provide.

Be aware of code review pitfalls. Otherwise, code reviews can slow your team down. Click To Tweet

Waiting for code review feedback is a pain

One of the main pitfalls code authors face is to receive feedback in a timely manner. Waiting for the comments to come in and not being able to work on the code in the meanwhile can be a huge problem. Even though developers can pick up other tasks to work on, if the code review takes too long, it impacts the developer’s productivity and also the developer’s satisfaction.

But, why does the code review feedback take so long?

Developers have to juggle several responsibilities

Well, code reviewing is not the only task the code reviewer has to perform. On the contrary, code reviewing – even though it can take a significant amount of time of a developer’s day-to-day work – is only one part of the responsibilities and tasks of a developer. So, it is very likely that the code reviewer is engaged in other activities and has to stop or finish those first before looking at the code review.

If the timing is not ideal, and especially if the code reviewer hasn’t anticipated this change coming along, chances are, it takes a while before she looks at the review. Remote teams also have to be aware of time differences. Otherwise, code reviews might even take longer.

Developers face problems if code reviews are not counted as actual work

Time constraints are real, and they affect both, the code reviewer and the author of the code. Doing a proper code review takes time. If teams want developers to do code reviews but do not value or count the time developers spend on code reviews, this becomes a real problem.

You have to value and plan for the time spent doing code reviews.
Photo by freestocks.org on Unsplash

You can't expect quality code reviews if you don't value the time a developer spends on them. Click To Tweet

Not rewarding code reviewing efforts and performance

It does not help to claim to value code reviews if you do not reward the effort developers spend on this task. Many companies focus on rewarding developers for the amount of code they write or the features they develop. This decreases the motivation and the ability of developers to do a good job helping each other (which includes code reviewing). Code review effort and performance should be a cornerstone for performance evaluation or promotion decisions.

If you want your team to do code reviews well, reward them for their work. Click To Tweet

Social factors and team dynamics

But waiting on a code review had not always to do with the lack of time or missing reward system. Due to its social character, delayed reviews can be due to insecurities or team dynamics. especially if the code review is overwhelming, or if the reviewer is new to the code, doing a code review can be overwhelming:

I’m expected to participate but I’m not quite sure how. I’ll wait until someone else starts.

(study participant)

Large reviews are hard to review

Another significant code review pitfall is large reviews. Imagine you are the reviewer, and you just got this review. You think, well, I am quickly going to look at that, but once you open the review, you see this large code change. Several files have been changed, and all changes tangle throughout the code base. What’s your first reaction?

Probably: holy cow!

That’s right. That is exactly what we saw when analyzing thousands of code reviews. Not only does review time increase with the size of the code change, but also feedback quality decreases. Well, that’s probably understandable.

10 lines of code = 10 issues.

500 lines of code = “looks fine.”

Code reviews.

— I Am Devloper (@iamdevloper) November 5, 2013

Large code changes are just incredibly difficult to review. If, in addition, the code reviewer is not that familiar with the part of the code base the change took place in, reviewing can quickly become a nightmare.

Large code reviews are hard to review. The quality of the review decreases with the size of the change, thus limiting the value teams get out of from code reviews. Click To Tweet

Understanding code changes needs some guidance

Understanding code changes, and especially the motivation for a code change is another code review pitfall many reviewers face. If there is no description explaining the purpose of the change, code reviewing becomes much harder. We saw in the study that if the code reviewer does not understand the code change, or if she is overwhelmed by the amount of change, she cannot give insightful feedback.

It’s just this big incomprehensible mess… then you can’t add any value because they are just going to explain it to you and you’re going to parrot back what they say.

interviewed developer13

Not getting valuable feedback decreases the developers’ benefit from and motivation for code reviews

Without doubt, spending the time on code reviews and not getting useful feedback back, is a problem. Even though the team might still benefit from the knowledge transfer, the developer’s motivation to do code reviews and the benefits from code reviews decrease when they do not get valuable feedback.

There are several reasons why reviewers do not or can’t give insightful feedback. It can be that the code reviewer did not have the right expertise. Another common reason is that the reviewer did not have enough time to look thoroughly through the change.

Maybe the code reviewer does not understand the code. It can also be that the code reviewer does not know what issues to look for. Understanding what makes for valuable code review feedback, and implementing code review best practices mitigates this pitfall.

Once the main discussion is about styling, you need to act

Another problem that can happen during a code review is called bikeshedding. Bikeshedding means that developers focus on smaller issues and start disputing minor issues and overlook the serious ones. The reasons for that are manifold. Common behind the scenes challenges that lead to bikeshedding are that developers do not understand the code change or that they do not have enough time for the code reviews. Sometimes bikeshedding can be a sign that there are issues with the team dynamics.

If people dispute about minor issues during code reviews, you have to take a look at the underlying issue. Time pressure, too large reviews, rivalry? Click To Tweet

Reaching consensus might need a face-to-face discussion

Sometimes it can happen that it is hard to reach a consensus. This can occur between code reviewer and code author, or also between several code reviewers directly. Such situations must be handled carefully as team dynamics are closely connected to these happenings. Communication via tools and in written form can aggravate this problem. If there seems to be any tension, or contentious issues to discuss, switching to face-to-face (either in person or via a video call) might be a good idea.

The benefits of code review outweigh the effort

I hope this list of code review pitfalls did not change your mind about code reviews. Because, the good news is that if you are aware of the code review pitfalls and counteract them, code reviews are a very beneficial engineering technique. And, there are even more proven ways to work effectively with code reviews.

Code review best practices

In the next blog post in this code review series, I show code review best practices to help to minimize the code review pitfalls and challenges and ensure your team gets the best out of the code review practice. So keep on reading. To be notified when I publish the next post, sign-up to my email list.

To never miss one of my posts, make sure you subscribe to my email list and let's connect on Twitter.

The post How to avoid Code review pitfalls that slow your productivity down! appeared first on Doctor McKayla.

How Code Reviews work at Microsoft

Michaela Greiler — Wed, 27 Mar 2019 08:00:57 +0000

Have you ever wondered how one of the largest software companies worldwide ensures high-quality code through code reviewing?

So did I. That’s why together with my colleagues, we investigated how code reviews are done at Microsoft. Is it a common practice? Are developers required to do code reviews? And which tools do they use?

Let’s find out in this post, which is part of a larger blog post series about code reviews showing you code review best practices, code review pitfalls, code reviews at Google, and much more.

To begin with, let me give you some key information about Microsoft. Microsoft has around 140.000 employees. Approximately 44% of them, that means over 60,000 employees, are engineers. Several products such as Office, Visual Studio or Windows are developed by thousands of engineers that work on the same code base simultaneously.

I say all this to give you some context and perspective of what it means to coordinate and manage the software development process. As you can imagine, it is a non-trivial task to ensure code developed by different sub-teams actually works perfectly together. And code reviews play a big role at Microsoft to allow smooth collaboration at such a large scale.

Code reviews at Microsoft are an integral part of the development process

One of the important facts when it comes to code reviews at Microsoft is that it is a highly adopted engineering practice. Thousands of engineers perceive it as a great best practice. And most high-performing teams spend a lot of time doing code reviews.

At Microsoft, code reviewing is a highly adopted engineering practice and perceived as a great best practice.

Click To Tweet

I prepared an exclusive Code Review e-Book for my e-mail subscribers to help you remember the code review best practices. I also added other great insights and summaries about code reviews. Get the 12 page insights to code reviews now. Not a subscriber yet? Just sign-up.

Exclusive Code Review Best Practice e-Book for my subscribers.

Investigating code reviews at Microsoft

Because code reviews play such an important role in the Microsoft development process, it was an ideal target for us to dig deeper and really understand the benefits and drawbacks of this practice. In a large scale study on code reviews at Microsoft, we interviewed, observed and surveyed more than 900 developers about their code review practices.

Our aim was to understand how exactly code reviews are done at Microsoft. We wanted to know, which code review pitfalls developers face while doing code reviews, and which code review best practices they develop to overcome those challenges.

What can you learn from code review practices at Microsoft?

Most of the lessons learned are as valuable to smaller teams and organizations as they are for large teams and large organizations. In case your team does not do code reviews yet, I distilled our findings in a way that shows you the benefits of the practice. I also explain how the code review life cycle looks like so you can incorporate that practice in your own development process.

If your team already does code reviews, you can compare your practice with the code review practice at Microsoft. Does your code review lifecycle look different? In the next posts, you learn from code review pitfalls and the code review best practices. With this information, you can set out to see if your team already implements all the best practices I present and overcome challenges. But, let’s get started:

How often do Microsoft engineers perform code reviews?

In this study, 36% of the developers said they perform code reviews multiple times a day. Another 39% of the developers said they do code reviews at least once per day. 12% do code reviews multiple times a week, and only 13% said they did not do a code review in the past week.

How often do Microsoft developers review code?

This means that developers at Microsoft spend a significant amount of their time on code reviews. So it is important to make sure that this time is spent worthwhile. But, which benefits does code reviewing provide?

Developers at Microsoft spend a significant amount of their time on code reviews.

Click To Tweet

Which benefits does code reviewing provide?

The most important reasons developers mentioned as benefits of code reviews are to improve the code quality and to find defects in the code. Another important benefit of code reviews is knowledge transfer.

Knowledge transfer means that team members that review each others code, become familiar with a larger part of the code base. But, it also means that code review best practices are developed within the team. Another advantage is that new team members and junior developers can learn and improve their coding skills while reviewing or getting feedback.

If developers discuss alternative solutions during code reviews, it not only improves the code base but has also a learning effect for all involved. Learning, mentoring and self-improvement are therefore all reasons code reviewing is perceived as such a beneficial practice at Microsoft.

Benefits of code reviews

Developers do code reviews to improve the code, to find defects, but mostly to increase the knowledge transfer amongst team members and for the learning effects.

Click To Tweet

But how does a developer typically do code reviews?

Code reviews can be performed in many ways. Sometimes, it is as informal as one developer walking over to another developer’s desk to look at some code together. Other times, teams review code together in groups. But the most likely scenario you will encounter for code reviews at Microsoft is that code reviews are done with the help of tools.

Code reviews at Microsoft are most often done via an internal tool

There is a wide variety of code review tools available, and at Microsoft, teams are free to choose their tooling. In 2016, 89% of the developers indicate to use the CodeFlow code review tool. I will explain more about this code review tool at Microsoft later. Since then, and with the rise of Git, the tooling landscape has changed. I’ll add updated numbers as soon as they become available. But, let us consider a typical review situation:

Let’ imagine a developer at Microsoft, and let us call her Rose. Rose just finished a part of a feature and now wants feedback from her peers.

How does Rose start a code review at Microsoft?

Well, as said, Rose is ready to get some feedback. Therefore she first prepares the code for review. This step includes that she opens the code review tool, that allows her to preview the code change. The code review tool performs some diffing tasks that help Rose to see exactly which changes she has done.

After carefully reviewing those changes, she prepares a small note that tells the reviewers what she did and why she did that. This note helps the reviewers to understand the purpose of the code change and its motivation. Now the code is ready to be sent to the reviewers.

How does Rose select the right code reviewers?

Many experienced developers know who should be on the code review. Nevertheless, for people new on the team, or for new areas of work the selection can be a bit more tricky. If Rose does not know who she should add, she would either look at the team policies or ask her colleagues. She can also use a recommendation feature of the code review tool that helps select reviewers based on experience and knowledge with the code base.

Who are relevant reviewers?

Rose selects reviewers that she thinks can contribute their knowledge to this piece of code. The reviewers are often other developers, but can also include other stakeholders, such as dev-ops engineers, UI experts, or also managers. Some reviewers are selected for their expertise, others are selected in order to stay informed about a coming change.

Common steps of a code review

Rose requests feedback from her peers

Once everybody is selected, Rose sends out the code review (by pressing the send button 😄! The code review tool sends notification automatically to inform everybody that a code review has been created. Obviously, notifications are sent to all reviewers. But, often additional parties, such as managers or product managers of other teams are also added to the notification list and are automatically informed for each review. Those notifications allow them to stay in the loop. They are not required to perform the review.

Receiving feedback is an iterative process

Once Rose’s colleagues have time, they will look at the code review. Each reviewer can annotate the code and add comments. Once finished commenting, the reviewer sends the annotated code back to Rose. Rose can now work on the comments and prepare a new improved version of the code.

Reviewers normally look for things like: does the code look bug-free? Is there an architectural problem? Are there minor issues such as missing comments, spelling mistakes? Not all comments are equally valuable. But, there are several best practices to boost the value of code review comments.

Rose prepares a new improved version of the code

Rose works on the feedback by fixing and addressing the suggestions. If Rose sees that there are some misconceptions or other contentious issues, she might walk over to a colleague to discuss this in person. That’s sometimes easier and more personal than through the tooling.

Anyway, once she finished working on all the feedback, she sends a new version of the code to the reviewers. That new improved version is called a revision.

If needed, she will receive further feedback. Whether or not this cycle continues for a few times depends on the type of change and its quality. For simple and small code changes, often only one code review revision is needed. For other more complex changes or changes in the problematic code, several iterations might be necessary.

It is totally normal, and partly desirable that this code review feedback cycle sparks some discussions between the author and the code reviewers.

All reviewers approve and Rose checks-in the code

After this review cycle, reviewers mark the code as okay, and Rose can finally check-in the code into the common code base.

Some teams have policies, that allow the developer to check-in the code before an actual review is completed. This is normally restricted to small and trivial changes, in order to allow asynchronous reviews and to speed-up development.

All steps I describe are part of a typical code review life cycle at Microsoft and are performed by all teams. Depending on the team’s policies, teams are more strict or rigorous for each of the steps.

Not all teams are the same

As you can imagine, not all 60,000 engineers, and not all of the thousands of teams do the same. Some teams at Microsoft have additional steps or tools they require during the code review life cycle. I want to give you a short overview of some additional steps that teams add to the code review process.

Code reviews including test results

The least what you want is to waste time by reviewing “automatic detectable” buggy code. I mean, if you could run automated tests and realize that the code does not work as expected, then, that’s what you should do: Run the tests before the review.

That’s why some teams require test results to be submitted with each code review. This way nobody can forget about running the tests. And it assures that the tests have actually run and passed for the given code change.

Other teams went even a step further and configured the code review tool in such a way that for each code review a developer submits, a build is triggered. That build contains that exact change, and also starts a series of automated tests. The results of this build and these tests are attached to the code review. Configuring it this way ensures that the code changes have been tested with the latest code changes from the common code base.

Code reviews including user interface

If changes affect the user interface, it is also a smart idea to require the developer to submit a screenshot. That way the code reviewer can see the effects of the code change without running the code. Second, the code reviewer can spot discrepancies when running the code on her own machine.

Code reviews including static analysis

Static analysis tools are only as good as their configuration, but, in terms of styling issues, they can save a lot of time for code reviewers. Some teams at Microsoft use automated static and dynamic analysis tools as dedicated bot-reviewers. Those bots comment on code styling and other static issues. Thus, freeing up time for human code reviewers to perform more interesting tasks.

Microsoft’s code review tool

For many years, one of the de facto standards for code review at Microsoft was an internal tool called CodeFlow. This is a sophisticated code review tool that supports developers and guides them through all steps of a code review. CodeFlow helps during the preparation of the code, automatically notifies reviewers, and has a rich commenting and discussion functionality.

CodeFlow is an UI heavy tooling, much like Word or PowerPoint, as you can see in the screenshot below.

Screenshot of CodeFlow (in 2016)

CodeFlow’s interface explained

You can skip this if you want, but for all interested, I am walking you through the interface of CodeFlow. Looking at the screenshot, on the left (A) you see all effected documents.

Also on the left, you see (B) the list of reviewers assigned to the review as well as their status (e.g., signed-off or pending). The active document is shown in the editor (C). At the bottom, you see (D) a list of comments for all documents.

On the other hand, in the active document (F) is one single comment. This comment is connected to the concrete part of the code (i.e., one word in a line). Finally, at the top, you see the overall status of the code review. In this case, completed. The numbers before signal the different revisions. In this review, there have been five revisions.

Commenting functionality

One of the nicest features of CodeFlow is its commenting functionality.

A code reviewer can select very precisely the parts of the code she wants to comment on. For example, a reviewer can even highlight just one or two characters in a line, instead of highlighting a whole row. Then, the reviewer can attach a comment to that selection.

The code author or other reviewers are notified of this comment and can start a conversation in the form of a thread around this comment.

Discussion functionality

This commenting functionality feels like commenting on social media platforms, such as Twitter or Facebook. Therefore, the commenting experience in CodeFlow feels very natural and allows for rich conversations and discussions. Another nice perk is the possibility to assign a status to each of these comment threads. The status can, for example, be “won’t fix”, “resolved” or “open”.

Comparison between code review revisions

A helpful feature is the possibility to select two different revisions of the code review and compare the differences between that. This means that you can see exactly which changes the code review author has performed between one code review revision and another one. That’s super handy to track the progress of the review.

Code review analytics tool

Developers spend a substantial amount of their time performing code reviews at Microsoft. To ensure this time is well spent, Microsoft has its own code review analytics platform.

This platform stores all code review data starting from the code under review, the developers involved in code reviews, to all comments of the developers. Even the code changes for each of the revisions can be traced back.

This code review data is the base for several empirical studies on code reviews at Microsoft. It is also used by many product teams for tracking their productivity and to understand their own code review practices. Also, many of the insights I share in this blog post series about code reviews at Microsoft stem from studies and analyses that involved this code review data.

The future of code review at Microsoft

With Micorosft’s engagement and acquisition of GitHub change was inevitable. The change is visible by the vast adoption of Git as a source control tooling within Microsoft for example. But, this also means that at Microsoft code reviewing in the form of pull requests is on the rise.

I’ll definitely plan to address code reviewing using pull requests at a later time.

Want more on Code Reviews?

Check out proven code review best practices, learn about which code review pitfalls you should avoid, and also how to boost your code review value with great feedback.

To stay in the loop and never miss a blog post, sign-up to my email list. Also, let’s connect on Twitter.

I prepared an exclusive Code Review e-Book for my e-mail subscribers to help you remember the code review best practices. I also added other great insights and summaries about code reviews. Get the 12 page insights to code reviews now. Not a subscriber yet? Just sign-up.

Exclusive Code Review Best Practice e-Book for my subscribers.

Credit where credit is due:

I would like to mention my wonderful colleagues at Microsoft and the University of Victoria that have been part of this study: Chris Bird, Jacek Czerwonka and Laura Macleod and Margaret-Anne Storey. I loved to work with you on this

The post How Code Reviews work at Microsoft appeared first on Doctor McKayla.

The Ultimate Code Review Blog Post Series

Michaela Greiler — Sun, 17 Mar 2019 13:40:13 +0000

Code Review: Lessons learned working at Microsoft
Photo by NESA by Makers on Unsplash

The post The Ultimate Code Review Blog Post Series appeared first on Doctor McKayla.

In this code review blog post series, I share my experiences and lessons learned about code reviews. Primarily, I show you code reviewing best practices to boost your code quality. But, you also learn which pitfalls to avoid while performing code reviewing.

The foundation of those code review blog posts is my experience analyzing and improving code review practices and tooling at Microsoft. I worked with hundreds of engineers and analyzed thousands of code reviews. You can see this code review blog post series as an intense crash course to learn about code reviewing best practices or as an opportunity to reflect on your own review practices.

Exclusive Code Review Best Practice e-Book for my subscribers.

I prepared an exclusive Code Review e-Book for my e-mail subscribers to help you remember the code review best practices. I also added other great insights and summaries about code reviews. Get the 12 page insights to code reviews now. Not a subscriber yet? Just sign-up.

Code review overview

Code reviewing is a widely adopted and adapted engineering practice. Its main aim is to improve software quality. In addition, sharing knowledge among team members is another important benefit of code reviewing.

Even though code reviewing provides several other benefits, you have to be aware to follow best practices. Otherwise, you might tap into several pitfalls.

Microsoft’s code review process

I have been working at Microsoft as a software engineer and researcher for several years. My main focus was to analyze and improve engineering practices and tools. One of the key areas I focused on was code reviewing.

In this blog series, I am going to share the key insights and lessons learned about code reviewing at Microsoft. All of them are backed by research and are grounded in actual experiences and knowledge from high performing engineering teams. At Microsoft, I performed several large-scale studies involving thousands of engineers and millions of code review comments. The lessons learned presented in this code review blog post series are derived from those empirical studies.

Peer code review happens with the help of tools, or also “over the shoulder”
Photo by Rachel on Unsplash

Blog post series

The series consists of 9 blog posts. You can read each one of them separately. Still, you might get the best out of it reading it consecutively.

In the coming weeks, I will post about:

Code Reviews at Microsoft In this post, I explain how a common review process looks like at Microsoft, and which code review tool is mostly used at Microsoft.
Code review pitfalls: learn which problems slow your team down In this post, I deep dive into the main code review pitfalls teams face when practicing code reviews.
Proven Code Review Best Practices Learn which code review best practices make your team productive and boost code review feedback value.
How to give great feedback The benefits of code reviews rise and fall with the quality and value of the feedback. In this post, I show you proven ways to boost your code review feedback.
Code Reviews at Google Code reviews at Google are lightweight and fast. Actually, code reviews are completed in under 5 hours. That’s much faster than for most other large software companies. In this post, I show you why.
Code Review Checklist If you want to boost your productivity and your rigor at the same time, a code review checklist is what you are after. This one is also downloadable.
How to give useful code review comments? Not every review comment turns out useful. Comments that are not useful should be avoided. In this article, I explain what really makes for a useful comment.
Code review trade-offs Even if you are aware of all best practices, there are several trade-offs you have to keep in mind. For example, do you favor review speed or review rigor? In this article, I dive into this topic.
Wrap-up post

Don’t miss out on any of the posts of this code review blog post series by subscribing to my mailing list.

As a subscriber, you profit, in addition to my awesome emails about software engineering, also from exclusive treats I prepare for you, such as my code review e-Book.

And I'm active on Twitter. Let us connect there.

The post The Ultimate Code Review Blog Post Series appeared first on Doctor McKayla.