Code Health Objectives Guidelines

Overview

The purpose of this guide is to help you and your team define objectives that will materially affect the health of the code that you are Code Stewards of, and/or enable your team to do so in the future.

The Code Health Metrics Workgroup was formed in 2019 to start working towards the creation of a base set of metrics that we could use to help measure code health. In addition to that, the CHMWG also worked towards putting in-place various enablers to help Code Stewards and maintainers understand and improve their code’s health.

Currently Code Health analysis and reporting is performed by Sonar Cloud. The key metrics reported out are: Maintainability, Reliability, Security, and Code Coverage.

Defining Code Health Objectives

As previously mentioned, CHOs are intended to identify actions to be taken on by Code Stewards that will materially impact the health of their code as measured by the aforementioned metrics. However, not all code, teams, and individuals are ready to take these kinds of action. As a result, enabling objectives may be the best course of action. Below are some questions that may help define some of the enabling CHOs.

Questions to help refine you Code Health Objectives

Are there any other ways to measure the code in question's health in addition to Maintainability, Reliability, Security, and Code Coverage? If so, further refining those measurements is a potential CHO.
Do you have an objective understanding of your code’s health? If not, setting up a CHO to gain that understanding is probably a good idea.
Are you equipped to make improvements to the code’s health as measured by the aforementioned metrics (i.e., do you know how to improve the maintainability of their code)? If not, engaging in training would be a good CHO.
Provided you understand how to measure code health, what the current level of code health is, and are properly equipped to make improvements, what are some improvement targets that could be set? The setting of those targets is a potential CHO.

Once you are ready to actively work toward materially affecting the code’s health, various other objectives can be pursued, such as refactoring work to enhance the modularity of the code.

Code Health Objectives Scope

In defining CHOs, there are generally two primary categories:

Team/Individual Level - These are CHOs that focus on the process and people. In theory, they impact all code that the team or individual works on. It is not necessary to break these down at the code level (i.e., repo, folder, file, etc…)
Code Level - These are CHOs that focus on the code itself. For example, enabling code analysis, setting metric targets, etc… are all things that need to be organized at the code level. The primary source for scoping these CHOs is the breakdown as defined on the developers/maintainers wiki page.

Logistics

In order to provide visibility and encourage broad engagement, Code Health Objectives will be documented and tracked on-wiki. Please see the Code Health Hub page for a list of Code Health Objectives. If you are an individual that would like to work on and/or create a Code Health Objective, please contact the Code Steward for the code in question in order to coordinate your efforts. Code Stewards can be found on the Developers/Maintainers page. If there's no Code Steward listed, please start a discussion on this page's talk page.

Approach Philosophy

Sustainable change is core to the theme of our approach. Although the change is focused on improving the health of the code, what is arguably even more important is the change in organizational and individual habits. Coupled with a strong desire to minimize impact on workload, this approach focuses on the priority work at hand.

What this means is that the priority is to apply Code Health improvements to currently prioritized work. On some occasions it may be necessary and/or desirable to do work that is specifically targeted at improving Code Health, but that should be the minority. The result of CHOs should not be a series of “Code Health Sprints”.

This approach is further enabled by patch level feedback from tools like SonarCloud, which provide real-time feedback to developers about the health of the code they are actively working on.

The desired end-result of this approach is that efforts are still focused on delivering the highest value in the eyes of the end user whilst incrementally improving code health and systematically improving our software development processes.

Improving your code’s health is like improving your own health. Sure you can go on a strict eating and exercise regiment in order to lose some weight, but if your habits don’t change because the behaviors are not sustainable, your health will revert.