Content from Introduction

Last updated on 2025-10-27 | Edit this page

Overview

Questions

  • What are the benefits of collaborative code development?
  • How can collaborating improve the quality and effectiveness of your code?
  • What practices and tools support effective collaboration?
  • Why should collaborative tools and workflows be adopted early in a project?

Objectives

  • Identify benefits of coding with others, including improved code quality and shared ownership.
  • Recognise common collaborative practices such as code review, pair programming, and version control.
  • Understand how early adoption of collaborative tools helps prepare for scaling up development.
  • Apply the practical collaborative strategy code review in a software project.

This lesson introduces key practices for effective coding and collaboration within research software projects. You will learn how to work together on code through structured approaches such as code review, understand common workflows and tools that support collaborative development, and explore the processes that help maintain code quality and team productivity. We will then take a practical look at how to carry out code reviews using GitHub, one of the most widely used platforms for collaborative software development.

Introduction to Coding Within a Collaboration

Software development thrives on collaboration, even when much of the coding is done individually. Getting input from others can have a big impact on the quality, maintainability, and effectiveness of your work, often requiring only a small investment of time. Since there is rarely a single “perfect” way to solve a problem, working with others allows you to share knowledge, skills, and perspectives, leading to better solutions and new insights. Through collaboration, you can learn new techniques, discover tools and infrastructure that streamline development, and help build a shared understanding that benefits the wider team or community.

What are the Benefits of Coding With Others?

There are many benefits to coding with others. Collaborative coding practices — such as pair programming, code reviews, and shared repositories — can help catch bugs earlier, improve code readability, and increase overall code quality. It also fosters shared ownership of the codebase, making it easier for teams to maintain and extend code over time.

Importantly, it is best to adopt collaborative tools and practices before they become urgent. Setting up processes, code sharing and collaboration platforms (like GitHub or GitLab), and development workflows early on means you will be ready to handle code review, version control, and team communication smoothly when collaboration intensifies. Early investment in collaboration infrastructure pays off by preventing confusion and bottlenecks later in a project.

Introduction to Code Review

What is Code Review?

Code review is the process of examining and discussing someone else’s code with the goal of checking its correctness and improving its quality and readability at the point when the code changes. It is a key collaborative and software quality assurance practice in software development that can help identify bugs early, ensure consistency with coding standards, and support knowledge sharing across a team.

Code review is valuable at all stages of the software development lifecycle — from initial design through development to ongoing maintenance — but it is best to incorporate it right from the start. According to Michael Fagan, the author of the code inspection technique, rigorous inspections can remove 60-90% of errors from the code even before the first tests are run. Furthermore, according to Fagan, the cost to remedy a defect in the early (design) stage is 10 to 100 times less compared to fixing the same defect in the development and maintenance stages, respectively. Since the cost of bug fixes grows in orders of magnitude throughout the software lifecycle, it is far more efficient to find and fix defects as close as possible to the point where they are introduced.

Why do Code Reviews?

Code review is very useful for all the parties involved - code author as well as reviewers - someone checks your design or code for errors and gets to learn from your solution; having to explain code to someone else clarifies your rationale and design decisions in your mind too. In general, code reviews help improve code quality, catch bugs early, and promote shared understanding among team members. They also support skill development and encourage consistent coding practices across a project.

The specific aims of a code review can vary depending on the context — for example, production-ready code might undergo rigorous scrutiny, while early-stage prototypes may be reviewed more informally for general structure and approach. Code reviews can follow a more formal process (e.g. structured pull requests with approval workflows) or take an informal shape (e.g. ad hoc peer review or pair programming), depending on the needs of the project and the team.

Code Review Types

There are several types of code review, each suited to different contexts and goals.

An informal review involves casually asking a colleague for input or advice. This type of review is often used to improve understanding, share skills, or get help with problem-solving, rather than enforce specific standards. Some examples include over-the-shoulder code review (when one developer talks the other developer through the code changes while sitting at the same machine) and pair programming (when two developers work on the code at the same time with one of them actively coding and the other providing real-time feedback).

A code modification & contrubution-based review occurs when changes or additions to a codebase are reviewed as they happen — commonly used in version-controlled software development workflows like GitHub’s pull requests. This approach is a bit more formal (e.g. structured pull requests with approval workflows) and tool-assisted, and focuses on ensuring understanding, clarity, maintainability, and code quality.

A more rigorous and formal method is the structured codebase review, such as a Fagan inspection, where a team examines a codebase systematically, following strict criteria to identify defects or ensure conformance to standards. While this method can be highly effective, it is resource-intensive and less common in the research software community (but it does occur). It focuses generally on conformance to processes and practices and identifying defects.

Code Review Practices & Processes

In this session, we will focus on code review practices centered around code modifications and contributions. The aim is to integrate code review into the research software development process in a way that is lightweight, low-stakes, and easy to adopt. Even a short initial code review can have a significant impact. As highlighted in “Best Kept Secrets of Peer Code Review” by Jason Cohen, the first hour of review is the most critical and productive, with diminishing returns thereafter.

The goal is to strike a practical balance: invest enough time to offer useful, actionable feedback without turning reviews into a bottleneck. When reviewing code, focus on:

  • Code quality - is the code clear and readable? Do functions serve a single purpose? Is it well-structured and consistent with the rest of the project?
  • Best practices and conventions - is the project’s coding style followed? Are tests and documentation included and up to date?
  • Efficiency and minimalism - does the change duplicate existing functionality (found elsewhere in the code or in a third-party library)? Is it limited to what’s required by the issue or ticket?
  • Knowledge sharing: ask clarifying questions (do not assume you understand everything or know best) and offer respectful, specific feedback. This helps everyone learn and builds team trust.

Given the value of that first hour, keep your efforts targeted. Do not spend time on:

  • Linting or style issues - automated tools or CI pipelines should catch these
  • Hunting for bugs, unless something clearly looks wrong — instead, check that tests exist for various cases that should catch bugs
  • Fixing unrelated legacy issues that pre-date the change — log those separately to avoid scope creep
  • Architectural overhauls — save big-picture changes for design discussions or dedicated meetings to decide whether the code needs to be restructured
  • Refactoring everything — provide only a few critical suggestions and aim for incremental improvement, not perfection.

In practice, code review often involves following a project-specific checklist to ensure consistency and alignment with coding standards. The process is typically iterative, with reviewers and contributors engaging in a cycle of discussion, updates, and re-review to address questions and refine changes before integration. If a conversation is taking place in a code review that has not been resolved by one or two back-and-forth exchange, then consider scheduling a conversation or a pair programming session to discuss things further (and record the outcome of the discussion - e.g. in the pull requests’s comments). This way - you can enhance code quality and collaborative learning.

Code Review Tools & Platforms

Modern source code management (SCM) tools such as Git, Mercurial, and Subversion are well suited for conducting code reviews focused on changes or contributions. These tools track modifications and provide clear “diffs” (differences) that make it easier to inspect code updates line-by-line.

On top of these, various higher-level software development support platforms — such as GitHub, Review Board, JetBrains Space, and Atlassian Crucible — offer additional features and tools to streamline the review process, including inline comments to facilitate discussions, approval workflows, and integration with issue trackers. Many projects also adopt custom workflows tailored to their specific needs, balancing formality and flexibility to best support their development practices.

Practical Work

In the rest of this session, we will walk you through how a code modification & contrubution-based code review process using pull requests in GitHub.

Content from Example Code

Last updated on 2025-10-28 | Edit this page

Overview

Questions

  • What does a bad code repository look like?

Objectives

  • Obtain example code used for this lesson
  • Describe the purpose of the example code repository

Creating a Copy of the Example Code Repository

For this lesson we’ll need to create a new GitHub repository based on the contents of another repository.

  1. Once logged into GitHub in a web browser, go to https://github.com/UNIVERSE-HPC/review-example.
  2. Select ‘Use this template’, and then select ‘Create a new repository’ from the dropdown menu.
  3. On the next screen, ensure your personal GitHub account is selected in the Owner field, and fill in Repository name with review-example.
  4. Ensure the repository is set to Public.
  5. Select Create repository.

You should be presented with the new repository’s main page. Next, we need to clone this repository onto our own machines, using the Bash shell. So firstly open a Bash shell (via Git Bash in Windows or Terminal on a Mac). Then, on the command line, navigate to where you’d like the example code to reside, and use Git to clone it. For example, to clone the repository in our home directory (replacing github-account-name with our own account), and change directory to the repository contents:

BASH 

cd
git clone https://github.com/github-account-name/review-example
cd review-example

Examining the Code

This repository contains code written in Python to analyse a dataset from the UK ResearchFish publication database. For the purposes of this training, we’ll be using this repository to make some high-level commits and create a pull request for review. It’s not necessary for us to delve deeper into how it works, but note that the repository contents have been modified to deliberately include many problem and errors!

Key Points
  • Encountering a “bad” code repository is an opportunity to learn what not to do!

Content from Fixing a Repository Issue

Last updated on 2025-10-27 | Edit this page

Overview

Questions

  • How do we approach grouping commits together for a pull request?
  • Can we use GitHub to directly make changes to files?

Objectives

  • Create an issue on GitHub that describes a problem with the example codebase
  • Use the GitHub file editor to make a direct change to a file in our example repository
  • Submit the fix for the issue on a new repository branch

Adding an Issue to the Repository

Let’s first add an issue to the repository, which will represent something we need to work on. For the sake of this exercise, it doesn’t really matter what the issue is, but perhaps we’ve spotted a problem with our codebase during development and we need to note this problem needs to be fixed.

If we look at the README for the repo we can see there’s a broken link near the top, so let’s register that as an issue.

  1. Go to your repository’s main page in GitHub in a browser, and select Issues at the top. You’ll notice a new page with no issues listed at present.
  2. Select New issue.
  3. On the issue creation page, add something like the following:
    • In the title add: Broken link to article
    • In the description add: The README link to the SSI website article is broken, resulting in a page not found error
  4. Assign ourselves to the issue by selecting Assign yourself.
  5. Assign the Documentation label to the issue.
  6. Select Create to create the issue.

QUESTION: who’s been able to create a new issue on the repository? Yes/No

Fixing the Issue

Now let’s assume at some future date we decide to fix the issue. Now in most cases, we’d probably do this by having the repository cloned on our machine, and then we’d make the change, and submit it that way. But in the interests of time and simplicity, we’ll just use GitHub’s direct file editing feature.

  1. Go to the repository’s main page
  2. Navigate to the README file in the file navigator
  3. Select the edit icon shaped like a pen/pencil on the top right
  4. In the file editor, fix the broken link by removing the bit that says “typo/”

So we now need to commit the change. It’s good practice when committing a change is to refer to the issue number in the commit message, which will give us traceability for changes back to the originating issue when looking at the commits in a repository.

  1. Select Commit changes... in the top right.
  2. This is the first issue on the repository, so let’s refer to that with #1 - Fix broken article link as the commit message
  3. We could optionally put more info about the fix in the description if we wanted

Now importantly, we want to submit this change as a pull request on a new branch, since this will allow others to review that pull request.

  1. Select the second option Create a new branch for this commit and start a pull request
  2. Enter a meaningful name for this new branch, e.g. readme-broken-link-fix
  3. Select Propose changes

This change is now submitted to this new branch. If you go to the main repository page and select branches, you’ll see our new branch in the list.

QUESTION: who’s managed to commit their fix to a new branch? Yes/No

Key Points
  • We use branches to contain the change commits we want to submit within a pull request

Content from Submitting a Pull Request

Last updated on 2025-10-27 | Edit this page

Overview

Questions

  • How do you create a pull request using GitHub?
  • How long should we keep a pull request open?
  • How do we request a review of a pull request?

Objectives

  • Create a pull request based on the changes we submitted to a new branch
  • Describe the reasons to keep a pull request short-lived
  • Request a review of your pull request from another participant

Creating a Pull Request

Let’s create a pull request now from this new branch.

  1. First, go the Pull requests tab at the top of the group repository main page, and select New pull request
  2. In the Compare changes page that comes up:
    • Select compare: and select your new branch, e.g. readme-broken-link-fix. You should now see a summary of the changes between the new branch and the main branch, i.e. a single commit and the fix you made earlier
    • Select Create pull request
  3. In the Open a pull request page that appears:
    • Add details for pull request before creating it, including a reviewer, label, title, and description
    • Enter a fitting title, brief description, and label
    • Select Create pull request

You’ll then see a summary of the pull request, including a summary of any conflicts with the base (main) branch, of which there should be none. There’s also an option to merge the pull request - but don’t do this yet, since you’ll need to wait for your pull request to be reviewed!

QUESTION: who’s been able to create a new pull request? Yes/No

Interestingly, even though we have created this PR to do a merge, we could continue developing our code on this new branch indefinitely if we wanted. We could make and push new commits to this branch, which would show up here, and we then merge at a future date. This may be particularly useful if we need to have a longer discussion about the PR as it is developing. The discussion would be captured in the comments for the PR, and when ready, we then merge the PR.

Callout

How Long should PRs be Open?

Which raises the question, of how long should PRs be open, or branches for that matter? To some degree, this depends on the nature of the changes being made. But branches in Git are designed, and should be wherever possible, short-lived and deleted when no longer required. The longer a branch is open, the more potential changes could be made to the main branch. Then when it comes time to merge the branch, we may get a lot of conflicts we need to manage. So generally, it’s a good idea to keep your branches open for a day or two, a few days maximum, before creating a PR and doing a merge if you can. Note that we can also see this PR, as well as any others, by selecting the Pull request tab.

Discussion

Obtain a GitHub Account ID from another Participant

For the next stage, you’ll be reviewing a pull request. Either:

  • If you are attending a workshop with other learners, the instructor will enable you to obtain a GitHub account ID from another learner so you can request a review of your pull request from them, and you’ll also be requested as a reviewer on someone else’s pull request.
  • If you are going through this material on your own, you can review the pull request you made on your own repository instead.

To assign your reviewer to your PR:

  1. Go back to your repository’s main page
  2. Select Pull requests, and then the PR you created
  3. Select Reviewers and add the GitHub account for the reviewer

You should see an orange filled circle next to their name, indicating that you have requested their review and they have yet to submit it. We could add as many reviewers as we want, particularly if this is a complex change that affects many aspects of the codebase.

QUESTION: who has managed to add the other account and request a review from them? Yes/No

Key Points
  • Try to keep pull requests short-lived to avoid them becoming outdated with other branches such as main
  • We can request reviewers for a pull request by adding their GitHub account to a list of Reviewers

Content from Reviewing a Pull Request

Last updated on 2025-10-27 | Edit this page

Overview

Questions

  • How do I submit a review of a pull request?
  • On what information about a pull request do I base my review?
  • What are the levels of approval for a pull request review?

Objectives

  • Describe how GitHub presents the information related to a pull request
  • Add review comments to a pull request
  • Submit a review of a pull request

Let’s now adopt a new role - that of the reviewer of someone else’s pull request (or PR for short).

Write a Review of the PR

To see a list of PR review requests for you, go to https://github.com/pulls/review-requested. You should see a review request from another participant, so select this from the list.

This will present an overview of the pull request (PR), including on separate tabs:

  • Conversation - an overview of the PR, including comments and other activities associated with the PR, as well as a summary at the end, indicating the overall status in terms of reviews requested, and whether there are any merge conflicts with the base branch (main in this case)
  • Commits - a list of all commits on the feature branch that have yet to be merged into the base branch
  • Checks - whether there are any automated checks implemented in GitHub Actions and their status
  • Files changed - the list of files and their line-by-line changes for this PR

If you select the Files changed tab, or if you select Add your review from the Conversation page which takes you to the same tab, you can then begin your review.

By default, the presented view indicates a “unified” view. This shows deletions highlighted in red, and additions highlighted in green.

Another view is the “split” view of these changes, which is selectable by clicking on the cog-like icon and selecting Split. This provides a side-by-side alternative, with the older version on the left, and the newer version on the right. In this case, you should see a number of green highlighted lines on the right side of this view, indicating the added lines.

When providing a review, we have the option of adding comments or suggestions inline to the proposed changes. By hovering over a line and selecting the + symbol at the start of the line, we’re able to add a comment on that line, for example if we spotted a spelling or grammatical mistake, or in the case of code, a programmatic problem or other issue.

We have the option of adding comments or suggestions inline to the proposed changes, if we want. For example, perhaps we know there is a Zenodo record for the code that this article points to, which we think should be added.

  1. Hovering over the line containing the fix and select the + symbol at the start of the line
  2. Add a comment, something like We should also link to the Zenodo record for the code, at https://zenodo.org/record/250494#.Y2UUN-zP1R4
  3. Then select Start a review

Can add as many comments as we want at this review stage, to any line. If this were a larger pull request, we would review all the other changes, and add comments as needed.

Finally, as a reviewer of this pull request, we can complete our review:

  1. Select Finish our review
  2. Add a brief comment, e.g. Overall, the changes look good, although we should consider adding the Zenodo repository link

And then we can select one of the following options:

  • Comment - where you’re just leaving a comment and aren’t requesting any changes
  • Approve - no comments are changes are necessary
  • Request changes - feedback must be addressed before it can be merged

For simplicity, let’s just go with the first option for this exercise.

Finally, select Submit review, and our role as reviewer on the pull request is complete! The originator of the PR can then take our review into account, and make changes in response to the review.

QUESTION: Who’s submitted a very brief code review? Yes/No

Callout

The Approve and Request changes options are unavailable!

If you’re following through the material on your own, and have reviewed your own pull request, you’ll notice that the Approve and Request changes options are not available. This is because GitHub does not allow users to approve their own pull requests. The reason for this is that it goes against the reason behind pull requests - to have others review your changes, and in a usual team environment, you’d ask a colleague (or colleagues) to do a review.

GitHub still allows you to submit a review to your PRs with comments however, so for the purposes of this training feel free to select the Comment option instead.

Key Points
  • The key reason to use pull requests is to ensure that code changes are reviewed by other team members before they are merged
  • We can elect to approve changes, request changes prior to merging a pull request, or block a merge until requested changes are satisfied
  • GitHub doesn’t allow the creator of a pull request to approve it

Content from Merging a Pull Request

Last updated on 2025-10-27 | Edit this page

Overview

Questions

  • How do I see the comments left by a reviewer?
  • How do I merge a pull request?

Objectives

  • Merge an approved pull request into its destination branch

Read Review and Merge the Pull Request

Now we return to our role as code contributor.

As owner of your PR, the next step involves addressing any feedback made by the reviewer. Return to the PR you created earlier, and take a look at the comments that will appear in the Conversation tab. You may need to scroll down to see them.

We should now consider the review and any observations or suggestions made, and make any needed changes. To add these changes, we’d add new commits to the PR branch, but for simplicity, let’s assume our reviewer fully endorsed our PR. We can go ahead and merge the pull request into our codebase, by selecting Merge pull request, and then Confirm Merge.

So now, our change has been integrated into our codebase! You’ll notice that the branch you created earlier has been deleted by GitHub, since it is no longer needed.

QUESTION: Who’s read the other participants’ review of their PR, and merged it? Yes/No

Key Points
  • Following a merge, pull request branches are deleted in keeping with the short-lived branch philosophy of GitHub