Augmented Analysis with Intelligent Notes

An augmented analysis lets you add contextual information to the analysis data as intelligent notes. In combination with hotspot analyses, augmented analysis provides a complete framework for managing technical debt, from detection to action.

Specify Contextual Information

Context matters:

  • What features do you plan to implement next and what parts of the system will they affect? If you know a particular module requires an extension, you might want to start by a set of pro-active refactorings to make the new feature cheaper and less risky to implement.
  • There’s always a trade-off between adding new features versus improving existing code. So how much can you spend on re-work and improvements?
  • Finally, there’s a decision to be made on when is a piece of code is good enough.

To account for these scenarios, CodeScene introduces the concept of augmented code analysis. An augmented analysis lets you specify contextual information which is then processed as part of the analysis. This means that the analyses are aware of your goals and can measure the progress towards them. Let’s get started with an example.

Augment Hotspots With Intelligent Notes

An augmented analysis is based on intelligent notes. CodeScene supports three different categories of intelligent notes:

  1. Planned Refactoring: Choose this category when you have investigated the code, perhaps with CodeScene’s virtual code reviewer or its X-Ray analysis and see the need to pay-off some technical debt in the short term.
  2. Supervise: Choose this category for code that might be acceptable for now, but that shouldn’t grow worse.
  3. No Problem: Choose this category to let CodeScene know that you don’t consider the code a problem. Perhaps you plan a replacement of the hotspot code, or the code is good enough for your purposes.

You can specify the notes and categories in either the Code Biomarker view, Fig. 49 or in the Hotspots map through the virtual code reviewer, Fig. 52.

Add a note in the biomarkers view

Fig. 51 Add a note to any hotspot in the Code Biomarkers view.

Add a note in the virtual code reviewer

Fig. 52 Notes can also be added to any file via the virtual code reviewer in CodeScene.

Once a note has been added, CodeScene will start to track it in every sub-sequent analysis. How CodeScene tracks a file dpends on the category you have assigned. Let’s look at the differences between the categories in the next sections.

Analysis Of Planned Refactorings

When you specify a Planned Refactoring, CodeScene will do the following, depending on how the code evolves over time:

  • Code Degrades: This will trigger a warning on the analysis dashboard since it violates the refactoring goal.
  • Code Improves: This gives you a thumbs-up as the goal was met and the code is now in measureably better state.
  • No Change: CodeScene understands that complex refactorings take time. However, if there’s no clear improvement over the next months, CodeScene will warn you about it. Perhaps you want to re-consider your goal or prioritize the refactoring?

The decisions – improvement, degradation, or no change – are based on the evolution of the Code Biomarkers for that particular hotspot.

Fig. 53 shows an example of how this information is reflected in the Code Biomarkers.

An example on how refactoring progress is reported.

Fig. 53 An example of how refactoring progress is reported.

In case of the darker future, painted in Scenario 1, CodeScene will also draw your attention to it through an analysis warning as shown in Fig. 54 that indicates that the organization missed a goal.

A warning that a planned refactoring hasn't been performed.

Fig. 54 A warning that a planned refactoring hasn’t been performed.

In this case, the warning occurs because of a planned refactoring wasn’t performed and the hotspot has continued to worsen. But the warnings are also fired in other situations. Let’s look at hotspot supervision to see another example.

Analysis Of Supervised Hotspots

Like we discussed earlier, you might chose a different trade-off and wait before undertaking a larger refactoring. Perhaps you know that the code in question is feature complete, or maybe you conclude that the code is acceptable after all. In that case you want to ensure that it stays that way. You do that by delegating the responsibility of supervising such hotspots to CodeScene as shown in Fig. 55.

CodeScene acts as an extra team member that constantly supervises code at risk to grow worse.

Fig. 55 CodeScene acts as an extra team member that constantly supervises code at risk to grow worse.

With hotspot supervision, you ensure that no new technical debt is taken on without you getting an alert from CodeScene.

Analysis Of Code Marked As “No Problem”

False positives show up every now and then in all automated code analyses and CodeScene is no exception. For example, there might be this gigantic hotspot file that is worked on all the time but just contains common declarations like enumerations or constants. While that might not be an award-winning design, such code is usually not a primary driver of excess development costs. Or maybe you do identify a problematic hotspot but know – again: contextual information – that this code will be replaced by a new library next month.

In that case you can make the decision to ask CodeScene to ignore a specific hotspot, and it won’t show up as prioritized technical debt in your next analysis.

However, there’s always a danger of suppressing warning signs or problems. Hence, CodeScene keeps analyzing ignored hotspots in the background even if you explicitly marked them as No Problem. Should something dramatic happen to that code, CodeScene will point your attention to it as shown in Fig. 56.

In the background, CodeScene continues to scan hotspots marked as No Problem to ensure they stay that way.

Fig. 56 In the background, CodeScene continues to scan hotspots marked as No Problem to ensure they stay that way.

CodeScene will also issue a warning on the project’s dashboard so that you can re-consider the goals for that hotspot.

View Your Technical Debt At A Glance

By augmenting your hotspots with contextual information and refactoring plans, you can then view your prioritized hotspots in the context of your goals and situation as shown in Fig. 57.

View your hotspots in context of your decisions and plans.

Fig. 57 View your hotspots in context of your decisions and plans.

Using CodeScene’s dashboard, you can even have the data updated in real-time as the code is being developed. That way, the whole organization gets to share a common view of what the state of the code actually looks like and how it evolves. That’s the first step towards true improvements.

Manage Your Intelligent Notes From The Dashboard

Most of the time you will interact with the intelligent notes via the virtual code reviewer or the Code Biomarkers view. But you can also get an overview of all notes and administrate them on a separate dashboard as shown in Fig. 58.

Manage your intelligent notes from their dashboard.

Fig. 58 Manage the intelligent notes from their dashboard.

The dashboard is particularly interesting for the hotspots classified as No Problem as they won’t show up in the other analyses unless CodeScene found a growing problem in them.

Know The Edge Cases When Tracking Hotspots

CodeScene does its best to track the notes you have attached to hotspots even if you move or rename the hotspot files. However, in some situations this isn’t possible. The reasons are due to the way Git works.

When CodeScene cannot find the file referenced by a note, that note will appear in the list of “Lost Notes” in the Augmented Analysis Dashboard shown in Fig. 59.

Manage disconnected notes from the dashboard.

Fig. 59 Manage disconnected notes from the dashboard.

The interface for lost notes lets you to decide what to do:

  • A file has been removed from the project. If this is the case, it’s time to remove the note as well. Just click on the Pen icon and select “Delete”.
  • A file (or an ancestor directory) has been renamed or moved. You should create a new note through the usual procedure, then delete the lost note.

The following situations are known to cause a lost note:

  • Deleted content: The most common reason for a lost note is that the original hotspot has been deleted.
  • Two-step renaming of content: Normal file renames work fine, but if the deletion step and the adding of the new file are performed in separate commits then CodeScene won’t be able to maintain the link from note to content.