<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Alistair Stead on Medium]]></title>
        <description><![CDATA[Stories by Alistair Stead on Medium]]></description>
        <link>https://medium.com/@alistair-stead?source=rss-ca1b58b16147------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*CMT71y3W9cHCoJlsQq9fRw.png</url>
            <title>Stories by Alistair Stead on Medium</title>
            <link>https://medium.com/@alistair-stead?source=rss-ca1b58b16147------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 23:12:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@alistair-stead/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Code Review: From Authoring to Feedback]]></title>
            <link>https://alistair-stead.medium.com/code-review-from-authoring-to-feedback-df71a35b3e7f?source=rss-ca1b58b16147------2</link>
            <guid isPermaLink="false">https://medium.com/p/df71a35b3e7f</guid>
            <category><![CDATA[feedback]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[code-review]]></category>
            <category><![CDATA[pull-request]]></category>
            <dc:creator><![CDATA[Alistair Stead]]></dc:creator>
            <pubDate>Mon, 08 Feb 2021 09:38:11 GMT</pubDate>
            <atom:updated>2021-02-08T09:38:11.364Z</atom:updated>
            <content:encoded><![CDATA[<p>Developers spend a large proportion of their time helping others; whether it’s bug fixing, coaching, sharing knowledge or reviewing. Support is delivered as part of our every-day lives — it’s a fundamental part of our identity and what developers do best — solve problems.</p><h3>Why Code Review?</h3><p>There are many benefits when teams adopt the practice of peer review. It’s vital for teams to build a shared mental model of how they operate. They should agree a set of standards and a vision or destination of the team — what is it they want to achieve? Peer reviews help to ensure that team members build and share knowledge together. They avoid intentional or accidental deviation from the standards and quality agreed to.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/451/1*EqQCG3DPy-7E_MnQM6ZTXQ.png" /></figure><h3>Striving for quality</h3><p>Teams often care about quality, or the standard to which something is done. There are many ways in which the quality of software can be measured, but there are typical reasons why quality (in any dimension) might not be achieved first time around: <strong>a difference in mental model, human error, or lack of information</strong>. All three can be improved with good communication and the introduction of quality checking in order to identify and remediate the quality issue. The chance of quality issues can be higher when teams move too quickly, don’t communicate, introducing unnecessary complexity or don’t have the right information. Teams also change — members join and leave, projects start and finish, and strategy is adapted to meet new challenges and opportunities. These changes can weaken the team’s ability to strive for quality.</p><h3>A tool for building culture</h3><p>Any interaction between members of a team affects team culture. While code reviews are primarily quality checks, often focused on problems, they are also an opportunity for positive feedback and a good opportunity to build culture. If done badly, it is equally an opportunity to damage or destroy culture — giving constructive feedback can be a difficult and skilful task — particularly when a significant amount of time and effort goes into producing a piece of work. Code review feedback is often text-based, which is unhelpful as context is often lost between writer and reader, making misinterpretation more likely. We’ll come to this later on.</p><h3>Nefarious behaviour</h3><p>Some behaviours are not in the best interests of a team or the ecosystem in which the team operates. These behaviours could be driven from an individual (for example, a developer pushing for quick review of code likely to cause production issues) or be imposed by the team itself (e.g. to meet a deadline). Code review acts as a checkpoint to evaluate whether the proposed change is in the best interests of the team. In the worst case, it’s possible that a developer is proposing changes that can cause harm to the team or business — e.g. building in a backdoor, or intentionally unsecured endpoint — the team is also responsible for self-policing to ensure this can’t happen.</p><h3>Practical code review</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/900/1*PkUJOJfWgZeVi26GOd0nDA.png" /></figure><p><em>I have felt for a long time that a talent for programming consists largely of the ability to switch readily from microscopic to macroscopic views of things, i.e., to change levels of abstraction fluently.</em></p><p>— Donald Knuth, “Structured Programming with <strong>go to</strong> Statements”</p><p>In this statement, Knuth captures the essence of what it means to be a programmer — abstraction is <em>necessary </em>when programming but also<em> useful</em>. Despite its uses, switching between different levels of abstraction is not totally natural, easy or error free. This is why it’s useful to<strong> explicitly review code more than once</strong> where each pass has a different type of quality consideration. Let’s use the analogy of a building inspection.</p><h3>The walk-around</h3><p>The first thing a building inspector might do is take a quick walk around the house to see if there are any obvious problems. In code, it’s signs of obviously <em>visible</em> issues such as:</p><ul><li>Is the syntax correct?</li><li>Are there any obvious problems with the structure or architecture?</li><li>Are there any gotchas or common mistakes?</li><li>Is this person using the standard/practice we want engineers to use?</li><li>Are they using tabs or spaces?</li><li>Is this a refactor, a restructure or a new feature?</li></ul><p>In many respects, this scan is the reviewer trying to understand <strong>what</strong> they need to review. The author can potentially support this by highlighting areas of concern and briefing the reviewer before they look at the code (e.g. via the PR Description).</p><p>The risk of a walk-around review is to believe that this is sufficient — this is very unlikely to be true. There are various reasons why this level of review is appealing, but in reality, it’s the <em>absolute bare minimum</em>. Authors can help to encourage more in-depth reviews by avoiding anti-patterns, which we’ll touch on later.</p><h3>Architectural Review</h3><p>This scan <em>explicitly</em> focuses on how the pieces of the structure fit together. The building inspector would be looking at the foundations, the structure, the facades, the waste removal and whether those are compatible with achieving the minimum requirements of the building. In the code, there might be focus on class structure, function re-use, code visibility, endpoints, internal and external dependencies and any security risks. Often the affordances of structures are more or less successful depending on the design of the structure and the success in implementing that design. For example, it’s possible to secure a REST endpoint (or a door in the analogy) to a reasonable standard, but the attack surface of the service would be reduced by definition if the endpoint didn’t exist.</p><p>There are a well understood set of <strong>design patterns</strong> (e.g. those defined by the GoF) within software engineering that overcome common problems in the structure and re-use of code. With experience, these patterns become easily identifiable and build confidence in the change, allowing the reviewer to shortcut some aspects of the review.</p><h3>Data flow Review</h3><p>A building inspector might want to review the pipework of the building and how water moves through it. Similarly, in software, code changes can influence the control flow and movement of data within a given service. The requirements of the system should specify what the expected amount of water (data) and pressure (throughput) will be. Taking this into consideration, the reviewer should be able to assess whether the system will be able to meet the requirements. Reviewers can do this by identifying bottlenecks that may cause concurrency failures, or memory spikes that may diminish the application’s ability to function. For example, are there a sufficient threads assigned to a thread pool? Is there a blocking action in a non-blocking call? Is there a cache? Is there a clear set of constraints around concurrent processes? Do potentially long running operations have timeouts or circuit breakers?</p><h3>Purpose Review</h3><p>The feature under review has been engineered to achieve a specific outcome. A simple question for the reviewer to answer is “does this work achieve that feature?” A building inspector might look at the initial brief, architectural drawings and regulatory requirements. The code reviewer must have information to understand what the author wanted to achieve (e.g. a ticket containing a set of clear requirements). They may have to fit this into an existing mental model of how the application works and then imagine the consequences of the proposed changes — this is not always easy to do and will likely benefit from some support from the author.</p><p>The reviewer may have to take the whole piece of work and then imagine how they might have tried to achieve the same requirements. If there’s a difference between the approaches, they might suggest discussing theirs — this may be difficult if there has already been a significant amount of work. Ideally there would have been earlier opportunities for the review’s design input.</p><p>If no purpose was clearly defined, it’s impossible for this part of the review to be completed — reducing a reviewers’ value significantly. This is a great opportunity to learn and share good practice.</p><h3>Good Practice and Anti-patterns</h3><p>When authoring and reviewing pull requests, there are some considerations that will generally help to ensure they are done well.</p><h3>Author Considerations</h3><p><strong>Deadlock Resolution</strong>: Sometimes developers engage in review discussion that leads to a deadlock situation in which a solution can’t be agreed. This may be due to a difference of opinion, a time sensitivity, or a lack of energy to do the required change. This is an incredibly sensitive situation with a high likelihood of misinterpretation and resulting sensitivity from either party. My advice in this circumstance is to change the medium — move to a phone/video chat if you aren’t getting to a resolution. The next option would be to invite an objective mediator who can help to resolve the dispute. If this fails, agree to collectively escalate for a decision to be made — try not to escalate independently as this may increase tensions further.</p><p><strong>Multi-purpose PRs</strong>: If your PR is intended to achieve many things at once, you will likely confuse the reviewers, or yourself. A great example is refactoring as you’re building a new feature — in your mind you’re cleaning up as you go. In the reviewer’s mind, you’re breaking down a mental model and ability to really understand what’s changed. Think of it as asking the building inspector to review your remodelled kitchen after changing the furniture and colour of the walls! It’s an unhelpful distraction. Refactoring also carries risk of merge hell and collision with other PRs — it is beneficial to do transactional refactoring and heavily communicate it to the team so that everyone knows when they have to merge as they work.</p><p><strong>PR Length:</strong> If the length of a pull request is very long (e.g. hundreds of files) the implicit message to the reviewer is they should either spend a significant amount of time (hours or days) reviewing the code, review in a superficial way, or they should just approve after doing a walk-around. Long PRs should be split into a number of smaller chunks. If the review is too short (e.g. one line in one file) the scope and impact of the change may become difficult to understand. The perception of the reviewer might be that the change is not sufficient to justify the overhead and distraction of reviewing.</p><p><strong>Reviewer requests:</strong> The number of reviewers and their experience also has implicit messages to the reviewers. Too few reviewers suggests this review is mainly focused on approval. Too many reviewers suggests low confidence in the change, or potentially that the review is so long it needs more engagement to catch all the critical issues. It may also lead the reviewers to believe that someone else will approve and they can just ignore until prompted. It’s useful to use a Goldilocks approach here by balancing the reviewers and ensuring that pull requests are of a reasonable length.</p><p><strong>Time sensitivity:</strong> Reviews are often time sensitive. Taking a long time to review and then waiting for long gaps between comment cycles is often frustrating for the author and reviewer. Context switching is painful for everyone. If big changes are needed, rather than a review cycle, consider pairing to make big changes quickly. Otherwise, dedicate time to be available to respond to questions or replies to ensure that everyone can continue to work.</p><p><strong>Definition of done</strong>: It should be clear what information is required for anyone to complete a code review within a given team. This can be done by creating a definition of done which can be agreed upon by the team and used to guide PR authors. This should be done as part of a PR template that authors can fill in when submitting their PR. The template should be agreed upon by the guild and the wider engineering team.</p><p><strong>Signposting</strong>: the author can help to guide the reviewers by signposting areas of potential need or contention and leaving commentary that may address any initial concerns. There is a balance to strike here as too many comments may distract the reviewer and cause them to miss issues in other parts of the code.</p><h3>Reviewer Considerations</h3><p><strong>Unnecessary comments:</strong> Sometimes reviewers feel they <strong>need to find problems</strong> others haven’t. This maybe because they feel they have to find issues to be useful or show value. Finding unimportant problems for the sake of it isn’t helpful; and should be avoided rather than blocking the review.</p><p><strong>Code Approval:</strong> Sometimes developers submit code reviews as a means to an end — in order to deploy a new feature or change. Really, this isn’t code review, it’s more like code <em>approval</em>. There may be lots of reasons for this: the change is small, the unit tests are no longer relevant, the urgency is high — we need to do this right now! Although this is understandable, it’s not desirable and often results in unintended consequences. Teams can avoid this by planning and communicating that reviews may be needed.</p><p><strong>Sensitive and Constructive Feedback:</strong> Humans are unique; individuals have a singular perspective on the world and have different views, experiences and sensitivities. When done well, feedback can lead to high performance. When done badly, it can diminish confidence, enthusiasm and self-worth.</p><p>Developers with <em>high sensitivity</em> to feedback are likely to misinterpret comments, extrapolate behaviour, and are at risk of taking feedback personally, causing anger, anxiety, stress, sadness, a feeling of imposter syndrome, bitterness or fatigue. This can be exacerbated if the feedback is given in public.</p><p>Developers of <em>low sensitivity</em> to feedback may not pay attention to, value, or care to consider feedback. They may not value the reviewer’s time or comments enough to engage in discussion or do more than the minimum to get through the review.</p><p>Ideally, feedback should be delivered on the code and not the human — it should be disassociated from the author where possible. It is the job of the reviewer to balance comments with sensitivity, NOT the author. The default position should be to tread carefully until otherwise informed. It may even be important to follow up outside of the code review to give context.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=df71a35b3e7f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>