- CodeScene measures several aspects of knowledge distribution:
Key personnel risks: Are there any critical parts of the codebase that are in the head of just one developer?
Low system mastery: What’s the impact if a developer leaves or moves to a different product line? Can you continue to successfully maintain the codebase?
Coordination bottlenecks: Are there any parts of the code where multiple teams have to coordinate their work? Such modules frequently lead to waste via merge conflicts and tend to be defect dense.
This guide shows you how to measure these aspects of your software development.
How Do We Measure Knowledge?¶
The knowledge metrics are based on the amount of code each developer has contributed. CodeScene looks at the deep history of each file to calculate contributions. This makes sense for two different reasons:
The last snapshot of a source code file wouldn’t be good enough since such shallow ownership is sensible to superficial changes (e.g. re-formatting issues, automated renaming of variables, etc).
Even if one developer completely rewrites a piece of code, its original author will still retain some knowledge in that area since they’re familiar with the problem domain. The metrics in CodeScene acknowledge that and will retain some knowledge for the original developer as well.
CodeScene uses the name of each committer to calculate knowledge metrics. So please make sure you understand the possible biases discussed in the guide Know the possible Biases in the Data.
Detect Knowledge Risks¶
CodeScene’s dashboard presents a high-level summary of the knowledge distribution and existing knowledge loss (e.g. code written by developers who have since left the company or project):
A high portion of code written by a smaller group of people might be a risk; when a core developer leaves, the knowledge loss increases and the lower system mastery makes it more risky to maintain the system. Using the Knowledge Risk view, you can identify those areas pro-actively:
The Knowledge Risks analysis identifies and highlights the following patterns:
Knowledge Island in Complex Hotspot: A module that’s written mostly by one developer, and that module is a hotspot with code health issues. Consider to on-board at least one more person in these areas as these hotspots present a significant key personnel risk.
Knowledge Island: A knowledge island is code written mostly by one developer, but the code is of acceptable code health. You might still face a key personnel risk, but on-boarding new personnel in this area should be lower risk than in complex hotspots.
Complex Code by Former Contributors: This type represents code with low code health, where the majority of that code is written by former contributors. It’s code with low system mastery. Modifying such code is always an increased risk, so make sure to schedule additional time for learning.
Multiple Active Developers: This type indicates that the code is actively worked on and that the detailed knowledge is shared by at least two developers.
Finally, note that CodeScene also presents warnings for knowledge risks as part of the virtual code review.
Explore the Individual Knowledge Map¶
In the interactive knowledge mpas, each color is used to represent the primary author behind a module.
CodeScene allows you to dynamically filter by authors and/or teams:
Tip: The knowledge maps are an excellent on-boarding support that helps new team members identify the colleagues that know that most about a particular piece of code. CodeScene’s knowledge maps go way deeper than a plain git blame and will present a more accurate picture of the primary authors.
In case of multiple authors, you click on a file – represented as a cicle in the visualizations – and explore who the other authors are:
Make sure Pair Programming is configured if needed¶
CodeScene also supports knowledge maps for pair- and mob programming, where the credits are split between the contributors in the pair. However, you need to configure your pair programming patterns in CodeScene to activate this feature. Refer to in Configure Developers and Teams for the configuration options.
Explore your Team Knowledge Maps¶
CodeScene also measures knowledge distribution on a team level and this information is usually even more valuable than the individual metrics.
As soon as you’ve assigned developers to a team, as described in Configure Developers and Teams, CodeScene will accumulate their individual knowledge into their teams. The analysis results are presented using the same principles as for the Individual Knowledge Map. Only now, each color represents a team as shown in Fig. 84.
The Team Knowledge Map lets you reason about both the responsibilities of the different teams. In general, you want to ensure that your team organization is reflected in the software architecture of your system. For example, the analysis in Fig. 84 has a configuration for three devlopment teams: Net, Unix, and Unicode. The analysis shows that each time has a clear area of responsibility. However, you get more details by clicking on the Coordination Needs aspect as shown in Fig. 85.
The coordination analysis shows you the parts of the code where multiple teams have to coordinate their work. From here you can explore which teams that are involved. The coordination analysis is also described in more detail in Parallel Development and Code Fragmentation.
Finally, make sure to read the discussions in the guide Social Networks for more information on the organizational theories and how they correlate to the quality and efficiency of your organization.
Measure from the date of the last organizational change¶
Development organizations aren’t static. People rotate teams, new teams are formed, and old ones abandoned. Each change introduces a possible bias into the team-level metrics.
The best way to avoid those biases is to select an analysis start date that represents the date of your last organizational change. For example, let’s say you changed the team structure back in January 2017. In that case you want to start your team analysis from that date, as illustrated in Fig. 86.
Note that you typically want to use a longer analysis time span for technical analyses. CodeScene resolves this by letting you configure two separate time spans, as illustrated in Fig. 86.
Uncover the Knowledge Loss in your Codebase¶
Knowledge loss represents code that is written by a developer who is no longer part of your organization or project. You use this information to reason about the knowledge distribution in your codebase and as part of your risk management since it is an increased risk to modify code we no longer understand. In addition, you can also use the analysis pro-actively to simulate the consequences, in terms of knowledge loss, of planned organizational changes.
The Knowledge Loss analysis will accumulate the contributions of all developers that you have marked as Ex-Developers in your configuration (see Configure Developers and Teams). Those parts of the codebase that are dominated by Ex-Developers are marked as red in the knowledge loss visualization. Fig. 87 shows an example from an organization where some core developers have left.
To inspect the knowledge loss you just click on a file, as shown in Fig. 88.
Note that there’s a special label in the knowledge visualization: Inconclusive. Inconclusive means that CodeScene cannot determine the original author of a piece of code. This is something that happens if you run a knowledge analysis on a shorter time span than the total lifetime of a codebase. CodeScene tracks moved and renamed content, but in doing so it depends on the underlaying object model of Git. So in the rare cases where copied content doesn’t get detected as such, the code may show up as inconclusive.