Are You Making These Common Empathy Mistakes in Your Pull Request Reviews?
--
Welcome to the third article of my series on stress management in the software industry. In this article, we will take a closer look at the approaches, mistakes, and best practices for reducing stress as pull requests through the lens of a reviewer.
As a software engineer, I believe that addressing stress is crucial to a successful career, and I am committed to continuing this exploration.
The pull request (PR) review process is meant to be a collaborative and constructive experience, but unfortunately, this isn’t always the case. When a PR is subjected to a non-ethical review, the stress levels of the person who submitted it can skyrocket.
Instead of being a supportive and helpful experience, non-ethical reviews often involve personal attacks, unjustified criticism, and unreasonable demands that can be incredibly disheartening and overwhelming. These types of reviews can leave individuals feeling frustrated, discouraged, and stressed, which can have a lasting impact on their confidence, motivation, and overall well-being.
The Importance of preparation: Strategies for a stress-free pull request review process
It’s important to not only focus on the review process from reviewer standpoint, but also on the steps that engineers can take before submitting their pull request (PR). As engineers, we have the power to set the stage for a smooth and constructive review process, and taking the time to prepare can help reduce the stress and ensure that our PR is received in the best light possible.
By taking proactive steps such as thoroughly testing our code, clearly documenting our changes, and seeking feedback from colleagues, we can help set the tone for a positive and productive review experience.
Remember, a well-prepared PR can not only reduce stress, but it can also lead to better outcomes and faster resolution times. So let’s take control and make the most of this important step in the software development process.
Testing before submitting PRs
I always advise my team members to run tests before submitting PRs. Why? Testing is an essential part of the pull request (PR) preparation process that should be noticed. Even if you have a dedicated QA team, testing your code thoroughly before the submission is critical.
After all, the ultimate goal is to ensure that your code works on your machine the same as on the deployment target machine. When estimating your task, feel free to include this time in your total time for completion.
As a result, you can help minimize potential issues during the review process and give yourself peace of mind by thoroughly testing your code. This process may entail running tests on your machine, performing small, targeted tests after deployment, or even enlisting the assistance of your colleagues to conduct a thorough review.
Remember that adequately testing your code can help prevent stress and frustration later on and lead to a smoother, more efficient review process. So, take advantage of this crucial step and thoroughly test your code before submitting your PR.
Prepare clear PR documentation
The second thing engineers could do before submitting the PR is to provide clear documentation. This is key when it comes to ensuring a smooth and stress-free review process. When submitting a pull request (PR), it’s important to not only have well-documented code, but to also include accompanying documentation that explains the changes you’ve made.
With documentation you will help reviewers understand the intent and logic behind your code. This not only makes their job easier, but it also helps to minimize the risk of misunderstandings or misinterpretations.
I belive that investing time in clear documentation is a worthwhile effort, as it can help to prevent frustration, minimize the risk of errors, and lead to a faster, more efficient review process. So take the time to properly document your code and accompanying explanations, and you’ll be well on your way to a stress-free review experience.
Uniformize your code for maximum efficiency
I like the standards because they tell me that I should just follow something that took a lot of work to make it acceptable to the community. The standards such as ISO and IEEE are crucial in ensuring quality and consistency in engineering. These standards are essential to enhancing the codebase’s quality, maintainability, and consistency. This is why a strong emphasis must be placed on adhering to coding standards in software development projects codebase.
As an engineer, when submitting a pull request (PR), it’s essential to ensure that your code aligns with your organization’s established coding standards and best practices.
This includes following naming conventions for variables, functions, and classes to increase code readability and maintainability, utilizing consistent code formatting to reduce bugs and enhance readability, implementing proper error handling with clear error messages and appropriate logging, providing well-commented code to explain its logic and provide context to reviewers, and following best security practices to minimize vulnerabilities.
There are a lot of tools which can help you with that, for example:
- https://github.com/hassanhabib/The-Standard by @hassanhabib
- https://plugins.jetbrains.com/plugin/7973-sonarlint
- https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarlint-vscode
- https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
- https://learn.microsoft.com/en-us/visualstudio/ide/create-portable-custom-editor-options?view=vs-2022
Once you setup these tools you can automation many things and focus on your coding and delivery.
This leads to a streamlined and efficient review process, reducing stress and ensuring the success of the software development project.
Conventional Commits
For me, using Conventional Commits has helped improve the quality and efficiency of my development process. This is why I recommend to use it and you as developer looking to improve your codebase and streamline of Pull Request workflow should give it a try.
There are a few reasons for this. With Conventional Commits, I have been able to keep my Pull Requests short and easy to review. In another hand, I have found it to be much easier to communicate the purpose and context of the changes being made to the codebase. This is because I structure my commit messages in a standardized manner.
Generally, I keep track of my changes by using a consistent commit message format and focusing each commit on a specific change. Reviewers can also provide feedback on specific parts of my code with clear summaries in my commit messages. It is easier to collaborate with other developers by creating smaller and more focused Pull Requests. Try it!
Visit this link to learn more about Conventional Commits.
Checklist Example Before Submitting PR
Here is my sample checklist that engineers can follow before submitting a pull request (PR):
Pull request reviews through empathic approaches
When it comes to pull request (PR) reviews, empathy refers to a style of code review that emphasizes understanding the motivations and context of the contributor. Instead of creating a confrontational environment for feedback and collaboration, this approach creates a positive working environment.
The aim of an empathic review is to understand why the change was made, what problem it was trying to solve, and how the solution was formulated. The reviewer and author can build trust and respect through this understanding, which will help identify any potential flaws or areas for improvement.
The key to an empathic pull request review is to provide specific, actionable feedback. It means providing feedback that is clear, concise, and directly related to the code being reviewed. A code review helps the author understand what needs to be improved and what needs to be changed.
Comments such as “this doesn’t look right” or “I don’t like this” are not helpful because they don’t provide specific information the author can use to improve the code. In contrast, specific, actionable feedback may include: “The variable ‘temp’ is not descriptive enough, consider using a more descriptive name such as ‘temporary_value’” or “This function is too long and complex, consider breaking it down into smaller, more manageable functions.”
It’s also critical to consider the context of the code and the author when providing feedback. Providing additional guidance and explanations may be helpful if the author is a beginner to the project or a particular programming language.
You can help the author improve the code by providing specific, actionable feedback. Everyone will benefit from better code quality and a more positive and collaborative environment.
Focusing on the code rather than the person is the key to success
The empathic review focuses on the code rather than the author. By avoiding personal attacks and criticism directed at the author, we can instead focus on improving the code itself.
Attacking an author’s code with personal attacks, such as calling it “lazy” or “stupid”, is counterproductive and only creates a confrontational environment. There can be hurt feelings, damaged relationships, and a lack of motivation as a result.
Instead, the focus should be on improving the code. It means providing specific, actionable feedback that focuses on the code rather than the author. Instead of saying “This code is terrible”, a more productive and empathic approach would be “This code could be improved by using a more efficient algorithm or refactoring it to make it easier to maintain”.
Maintaining a positive and constructive work environment for feedback and collaboration can be achieved by focusing on the code and avoiding personal attacks. As a result, the code will be better and the relationships between team members will be stronger.
Respecting and being professional at all times
In order to conduct an empathic pull request review, being respectful and professional is crucial. You should use language that is professional, respectful, and appropriate, regardless of whether or not you agree with the changes that have been made.
If you use disrespectful or unprofessional language, such as making personal attacks or using offensive language, it will not be productive. This will result in hurt feelings and damaged relationships between you and others. If this occurs, it can create a confrontational and negative environment that inhibits collaboration and improvement in the workplace.
Even if you disagree with the changes, use professional and respectful language. Focus on improving the code with polite, constructive language. “This is a stupid change” can be said more respectfully and professionally by saying “Can we jump on call, I can share with you a trick that has saved my life many times”.
Creating a positive and constructive feedback environment requires respect and professionalism. As a result, the code will be better and the relationships will be stronger.
Checklist or Reviewers
Reviewers can use the following checklist to ensure they provide effective and empathic feedback:
Study the impact of pull requests on software development
While researching this article, I asked developers to share their perceptions of pull requests and their impact on software development. The results are analyzed here.
How would you rate the emotions you typically experience when creating a pull request?
Emotions experienced when creating a pull request: The responses vary between frustration, satisfaction, embarrassment, and excitement, with ratings ranging from 0 to 10. It is interesting to note that frustration is a common emotion experienced by many developers when creating pull requests.
How would you rate your feelings after finally submitting a pull request that you have been working on for an extended period?
The majority of developers reported feeling satisfied or excited after submitting a pull request. This indicates that the act of completing and submitting a pull request is generally seen as a positive accomplishment.
How did you feel when you received feedback on your pull request?
The most common emotion reported in response to receiving feedback on a pull request is frustration, which suggests that some developers may struggle with feedback that is critical or difficult to address.
How would you rate the impact of your confidence level on creating a pull request?
Most developers rated their confidence level as having a moderate impact on creating pull requests, suggesting that confidence is an important factor but not necessarily the most critical one.
How would you rate the impact of the fear of rejection on the creation of a pull request?
The fear of rejection was rated as having a moderate to high impact on creating pull requests, indicating that some developers may be hesitant to submit pull requests for fear of negative feedback.
What suggestions would you provide to other reviewers to enhance the review process for pull requests?
The most common suggestions for enhancing the review process include adding proper reasons for comments, breaking up larger pull requests, focusing on best practices rather than business context, and choosing words carefully when leaving comments.
What recommendations would you give to other developers to ensure pull requests’ successful and efficient creation?
Most developers recommended that pull requests be kept small, that developers review their own code before submitting, and that the team be kept informed of changes to the project.
In your experience, what is your general view on pull requests? Do you feel they are an efficient and effective tool for ensuring high-quality software development? Additionally, are there any alternative approaches that you would recommend exploring to improve the pull request process?
Overall, developers view pull requests as an effective tool for ensuring high-quality software development. However, some also noted that the process can be frustrating or unpleasant if reviewers are unpleasant or critical.
No alternative approaches were recommended by the survey respondents, indicating that the pull request process is generally seen as effective and efficient.
In conclusion, this survey suggests that pull requests are generally viewed positively as a tool for ensuring high-quality software development. However, there are some challenges associated with the process, including frustration and fear of rejection.
To address these challenges, developers recommended breaking up larger pull requests, focusing on best practices, and reviewing one’s own code before submitting. Additionally, it is important to choose words carefully when leaving comments to avoid causing frustration or offense.
Finally
By testing their code thoroughly, providing clear documentation, and adhering to coding standards, engineers can minimize stress in the pull request review process.
The reviewer, on the other hand, can use empathic approaches by empathizing with the code rather than the person, providing specific and actionable feedback, and being respectful and professional.
The survey reveals that frustration and fear of rejection are common challenges. However, software engineering teams can overcome these by breaking up larger pull requests, following best practices, reviewing one’s own code before submitting, and carefully selecting words when leaving comments. As a result, best practices can speed up resolution times and improve outcomes.
We can provide constructive feedback that leads to better code quality and stronger team relationships. This can be done by focusing on the code, avoiding personal attacks, using professional and respectful language, encouraging discussion, and considering the context. Consistent and effective feedback can also be ensured by using a checklist.
Software development cultures and companies can be productive if a constructive environment is created for feedback and collaboration.
P.S. If you believe I can help with something, don’t hesitate to contact me, and I will reach you as soon as possible. admir.m@penzle.com
Cheers! 👋
