Which branch?
CodeScene should be configured to analyze the branch to which most PRs are merged. This is usually your main or master branch.
If you use main or master as a release branch, then probably most of your PRs are merged into a development (or develop) branch. In this case, CodeScene should be configured to analyze the development branch.
PR size
We strongly recommend smaller PRs. This is an industry-wide best practice that reduces the risk associated with each PR. It also makes code reviews easier and more reliable. All stakeholders benefit from short feedback loops.
This goes for CodeScene’s automated code reviews as well. It will be easier for developers to understand and react to CodeScene’s comments if the batch size is small.
Tip: Use feature flags/toggles to break up larger features into smaller deliveries. You don’t need a complex framework for this: a simple, hard-coded boolean flag can be used to disable work in progress, letting you benefit from small and reviewable PRs.
Shift left: get a code review before opening a PR
Let each developer install the CodeScene CLI tool. Use the provided script as a Git pre-commit hook. That way, CodeScene CLI will automatically give you feedback on any Code Health decline the moment you do a Git commit.
VSCode users can also use our VSCode plugin.
Naming conventions
We strongly recommend that developers add issue identifiers from your PM tool (Jira, Azure Dev Ops, GitHub Issues, etc.) to all Git commit messages.
Typically, this looks something like this:
MYPROJ-1234: fix rendering bug
In general, this enables traceability. It also allows CodeScene to accurately connect development work with PM data. This enables some of CodeScene’s important Delivery analytics and improves the identification of change coupling as well as bugfix commits.
For projects using pull requests, CodeScene also supports using PM issue identifiers in branch names.
Code Health Strategies
The first step in dealing with technical debt is crucial: don’t make things worse. That’s the purpose of using CodeScene’s pull request integration as a quality gate.
At first, the amount of feedback might seem overwhelming, and it may be tempting to relax or disable some of the Code Health rules, to go faster. Our research has shown, however, that quality is not the enemy of speed. Getting a handle on Code Health issues in your project will lead to faster outcomes.
Ignoring or relaxing Code Health rules should only be done after careful evaluation, and preferably after your team has been working with CodeScene for an extended period.
Naturally, there are situations where it’s not possible to address a Code Health issue in the scope of a single PR:
- Extreme time constraints (hotfix)
- Large refactorings are required for small changes: adding one or two lines to a file or a function that was already too long will trigger a violation. This should be an invitation to refactor the file or the function in question. However, if this refactoring is a major undertaking, such as splitting a module into submodules, then it may be preferable to plan this refactoring as a separate task.
In cases like these, we recommend using CodeScene’s Suppressions feature. Suppressions allow the PR to pass the quality gate while allowing you to document why you chose to ignore the issue temporarily. The suppressions can then be reviewed later and incorporated into refactoring plans.
To suppress a finding, click through to CodeScene from the PR. You’ll see the finding and have the choice of suppressing it.
Over time, developers will gain familiarity with CodeScene’s recommendations. This will prevent further declines in Code Health. That will be the ideal time to start using CodeScene as a prioritization tool for improving the Code Health of hotspots in your code.