How To Use Sourcery For Code Reviews?¶
In this guide, we're introducing some functionalities of the Sourcery CLI that can make your code reviews:
- more consistent
- faster
We're discussing this in 3 sections:
- Scope: How to ensure that the review focuses on the current PR?
- Content: What types of checks to execute and how?
- Automation: How to automate some of the checks?
If you haven't installed the Sourcery CLI yet, check out our guide to set up the CLI first.
Scope: Focus On The Current PR¶
Before we dive into the various types of checks, let's make sure we get the scope right. The bigger and more complex your project, the more difficult it is to isolate the current change. And the more tempting it is to try to fix some long-standing legacy issues and hijack the scope of the code review.
To focus only on the current change, you can use the
--diff
option This way, the check
runs only on changed code returned by a diff
command.
For example, to review the changes compared to the main
branch:
sourcery review --diff "git diff main" .
All the following examples assume that you're reviewing the changes of a PR
compared to the main
branch.
Content: What Types Of Checks To Execute?¶
Sourcery's current Python rule set contains:
- almost 200 default rules;
- more than 50 optional rules;
- rules defined by you specific for your project.
Which of these you find relevant depends a lot on your codebase. It might even change from PR to PR. A common practice is to enforce only the default rules for your entire codebase, but have higher standards for newly added code.
Basic Code Quality¶
A good first step is a general code quality check. For that, run the review
command with specifying only the --diff
option (see above):
sourcery review --diff "git diff main" .
By default, Sourcery runs:
- the 200 default rules
- the rules defined in your project's
.sourcery.yaml
config file
Focusing on Specific Aspects of Code Quality¶
Besides running a general check, you can get more specific and focus on various
aspects of code quality. For that, you can use the
--enable
option with a rule ID
or a tag.
For example, to check whether all new names adhere to PEP-8 standards:
sourcery review --enable gpsg-naming-pep8 --diff "git diff main" .
In a similar way, you can also check whether the PR has added the necessary docstrings:
sourcery review --enable gpsg-docstrings --diff "git diff main" .
Cleanup Checks¶
A code review is a great occasion to detect stuff that was helpful during development but shouldn't stay around in the production code.
One such check is to ensure that the PR doesn't contain any debugging, including
print
statements:
sourcery review --enable no-debug --diff "git diff main" .
Project Specific Checks¶
While there are many best practices, some conventions are specific for your codebase. For these, you can set up custom rules using the very same syntax Sourcery uses for the default and optional rules.
You can also create some common types of rules using the Sourcery Rules Generator.
Let's say your team has agreed that you don't use the term "util", because it's
too general. You can
create naming rules to detect names
containing "util" using the voldemort
template.
sourcery-rules voldemort create
Afterwards, you can add the generated rules to your .sourcery.yaml
config file and execute them with
the --enable
option:
sourcery review --enable no-util --diff "git diff main" .
Automate The Repetitive Parts: Create A Rule Tag For Code Reviews¶
A great way to accelerate your code reviews is to automate at least a part of
these checks. For that, you can define a
rule tag in your
.sourcery.yaml
config file
rule_tags:
code-review:
- gpsg-naming
- gpsg-docstrings
- no-long-functions
- no-debug
- no-util
This config file can evolve as you figure out which types of checks are general during a code review.
You can also set up separate tags for various types of code reviews. For example:
- code-review-hotfix
- code-review-new-feature
You can also take the automation one step further and set up a check in the CI