Which is better for code reviews, a unified diff or a split diff?
Code reviews are an essential part of the software development process. They allow developers to collaborate, identify bugs, improve code quality, and share knowledge. One crucial aspect of code reviews is the diff view, which shows the changes made to the codebase. There are two common types of diff views: unified diff and split diff. In this blog post, we will explore the pros and cons of each and discuss which one is better for code reviews.
Unified Diff vs. Split Diff
A split diff view presents the code changes side by side, with the original code on the left and the modified code on the right. This format allows reviewers to compare the changes directly and easily spot the differences. On the other hand, a unified diff view shows the changes in a more compact format, with the added lines marked with a “+” symbol and the removed lines marked with a “-” symbol. This format is easier to read for small and simple changes.
For simple and small changes, both unified and split diff views can be effective. However, when dealing with larger and more complex changes, neither format may be sufficient. Reviewing a large change requires a comprehensive understanding of the codebase at a particular instant in time, paying attention to the recently changed areas, and conducting a general review as if writing the code from scratch.
Running tests, using navigation features like “goto definition,” and considering the wider context are crucial for a thorough code review. Additionally, reviewers need to be able to notice anything that might be not quite right with the codebase, regardless of the historical path to the current state of the code.
The Ideal Diff View
Based on the author’s experience, the ideal diff view would combine elements of both the unified and split diff formats. The left side would display the current state of the code, with changes subtly highlighted in the margins. On the right side, a unified diff for the portion of the codebase currently visible on the left would be shown.
Unfortunately, the tools commonly used for code reviews do not provide strong support for this ideal diff view. Most tools focus on reviewing the changes themselves rather than the actual code. However, the author has developed a low-tech and somewhat inefficient workflow to achieve this style of code review.
The author uses a custom script to check out a pull request locally, which erases all the commits from the pull request but keeps all the changes. This allows the author to review the code using familiar staging and committing workflows. The author also mentions using the “edamagit” tool, which provides shortcuts for navigating through changes in the editor and even allows marking reviewed hunks using the staging area.
However, the author does note one limitation of this workflow: the lack of automatic synchronization between the “magit status” buffer and the currently open file in the editor. To view the current file and the diff side by side, the author must manually open the diff and scroll to the relevant point.
In conclusion, while unified and split diff views have their advantages for code reviews, neither format may be ideal for larger and more complex changes. The author suggests a hybrid approach that combines elements of both formats, allowing reviewers to have a comprehensive understanding of the codebase while still being able to focus on the specific changes. Although current tools may not fully support this ideal diff view, the author has developed a workaround to achieve a similar workflow.
Overall, code reviews play a crucial role in maintaining code quality and fostering collaboration among developers. Finding the right diff view that suits the needs of reviewers can greatly enhance the effectiveness of code reviews and ultimately lead to better software.
Unified versus Split Diff