Teamscale Documentation

Appearance

Best Practices for Static Code Analysis ​

Just installing a tool and hoping that your code quality will improve as a result usually doesn't work out. Lasting improvements only happen when we can motivate engineers to continuously care for and work on code quality. This will only happen when we make our tools easy and effortless to use and deeply integrate them in our development process and practices. The following sections list best practices that help you become effective at continuously improving software quality in your project.

Choose a Technical Quality Engineer ​

Every great cause starts with a leader. Someone who champions the cause in the team, makes sure there's a clear goal and everyone stays on track. For software quality, we like to call this person the technical quality engineer (TQE).

The only real requirement for the job is: They must care deeply about your software system's quality. We do however recommend that the role be filled by someone who "lives close to the code" (thus, technical quality engineer), i.e. a full- or part-time developer, since technical knowledge about the code, the system's architecture and the development process make a TQE's job much easier.

The TQE is responsible for both Teamscale and the quality improvement process.

In essence, the TQE acts a as a counter-weight to the "daily business", deadlines and the urge to implement new features at the expense of long-term quality improvements. Our experience is that without such a clear owner for the quality process and tooling, teams won't achieve lasting improvements.

This role can be filled by anyone from your team or even an external person. It is not a full-time job but rather requires only a little extra time every sprint.

Quality Control as a Service

For some of our customers, we from CQSE act as the TQE and bring an unbiased outside perspective to the table. As software quality experts with many years of experience, we challenge the teams regularly and help them tackle their technical debt effectively.

Choose a Quality Goal ​

Don‘t waste your time sorting through endless lists of findings! When you first install a new analysis tool, you'll probably find thousands of findings. Trying to read these long lists and manually prioritize which findings to address first is tedious and ultimately a doomed strategy as the business expense cannot be justified in the long run. Furthermore, fixing findings all over your system may do more harm than good, e.g. introduce bugs and regressions by accident.

We recommend a much more cost-effective and less risky approach.

Every team agrees on one of the following quality goals.

  • Either: at least don't make the system any worse, i.e. clean up all new problems.
  • Or: actively improve the system by cleaning up all changed code.

Read more about quality goals in our article on effective quality improvement.

Teams use these to set explicit, clear expectations towards how they will tackle the mountain of problems identified by Teamscale continuously. They are based on a "clean up where you work" strategy (a.k.a. the boyscout rule: "leave the camping site cleaner than you found it").

  • This is cost-effective as you only clean up in code areas where you're already making modifications and already have to understand and test the code anyways.
  • This is low-risk as you're making changes in areas that you have already understood, modified and will test afterwards. So there's less chance of breaking something accidentally.

The TQE continuously monitors whether the team is meeting their self-imposed goal and takes action if they don't.

Your Pull Request is Your Quality Gate ​

The idea of a quality gate is traditionally to "break the build" or "halt the release" if certain key performance indicators (KPIs) are not met. In our experience, this approach is rarely effective:

  • Breaking the build as a quality gate interrupts and blocks the whole team and it's unclear who is responsible for fixing it. This is ineffective and furthermore, your team will soon learn to hate the tool that forces them to regularly fix other people's problems.
  • Halting the release happens too late in the development process, so there's usually too much at stake and thus these quality gates often get ignored on purpose.

Thus, traditional quality gates fail to deliver on their promise of substantially helping to improve software quality. Instead, we need an approach that addresses single persons directly, does not prevent others from working and gives feedback as early as possible.

Thus, instead of one big quality gate, we recommend you use pull requests (e.g. in GitLab, Bitbucket, GitHub or Azure DevOps) as lots of regular, small quality gates.

Don't merge a pull request unless it's clean.

I.e. it introduces no new Teamscale findings. In fact, don't even send a pull request with Teamscale findings into the code peer review. Save yourself and the reviewer some time and address the problems Teamscale can find first.

If a pull request surfaces problems that are too big to solve between just the developer and reviewer or you are under pressure to merge, let the TQE know and discuss it in the next sprint retrospective. This hints at larger underlying issues that you need to address as a team.

Choose a set of KPIs and ensure they consistently improve. We suggest:

Meeting absolute KPIs is less important than continuous progress.

Especially in long-lived systems, you'll likely find yourself far from your ideal target. Spending huge effort on cleaning up old problems makes no business sense and is risky. Thus, you're unlikely to reach your idealistic KPIs any time soon. Instead, focus on small, continuous, regular improvements in these KPIs. This is achievable, rewarding, low-risk and creates lasting business value. And Teamscale makes it easy to track this both on dashboards and with PDF reports.