Manage Hotspots and Technical Debt with Goals

CodeScene lets you add contextual information to the analysis data as specific _goals_. In combination with the hotspot analyses, CodeScene’s goal-oriented workflow serves as a framework for managing technical debt and code quality issues, 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.

By planning a goal, you specify such 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.

Plan a Goal for a Hotspot

CodeScene supports the following goals and categorizations of code:

  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. Supervise lets you put a quality bar on existing code, which is particularly useful in legacy codebases.

  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 you consider the report a false positive.

  4. Critical Code: Categorize a module as Critical Code to have it indicated in Pull Requests when modified, included in the PDF reports, and supervised for risky changes. Typical use cases involve tracking code that’s business critical or has security impact.

You can specify the goals and categories in the Code Health view. Goals can also be specified on any file via the virtual code reviewer in CodeScene.

Add a goal in the biomarkers view

Once a goal has been added, CodeScene will start to track it in every sub-sequent analysis. How CodeScene tracks a file depends 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 goal, 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?

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.

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 even though we do our best to filter them out. 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 by issuing a warning on the project’s dashboard so that you can re-consider the goals for that hotspot.

Analysis Of Code Marked As “Critical”

All files marked as “critical code” are listed in a dedicated view where you can inspect their evolution.

Files marked as “critical code” are highlighted in CodeScene’s code review recommendations given on Pull Requests. This is important since critical code often has security implications and a detailed code review is recommended:

CodeScene notifies reviewers when critical code is modified.

Fig. 27 CodeScene notifies reviewers when critical code is modified.

During an analysis, critical code acts like the “Supervise” goal. That is, any code health decline leads to a failed goal and is reported as such.

Manage Your Goals From The Dashboard

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

Manage your goals on their dashboard.

Fig. 28 Manage the goals on 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 goals 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 goal, that goal appears in the list of “Lost Notes” in the Hotspot Goals Dashboard.

The interface for lost goals 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 goal:

  • Deleted content: The most common reason for a lost goal 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.