C.3 Code Insights

Understanding SheerPower's Option Insights Feature

SheerPower’s option insights causes sheerpower to collect detailed metrics during compilation to generate a comprehensive Code Insights report. This feature analyzes code complexity and structure, making it an invaluable tool for writing code that is easier to develop, test, and maintain.

Enabling Option Insights

To enable Insights, simply add this to the top of your program:

option insights

SheerPower tracks various metrics during compilation and automatically generates a detailed Insights report at the end of the process.

Note: To use insights, you must install SheerPower. Insights are generated when option insights is enabled and you validate or deploy your program.

Generated Report

The insights report provides the following key details:

Lines of code, number of routines, and variables.
Complexity level per routine.
List of most complex routines.
List of unused variables -- they were given values but never used.
Literal counts.
Suggestions for optimization.
and more.

The report is generated in HTML format and can be viewed in any browser.

Interpreting the Scores

The report assigns a Complexity Level score to each routine:

(Show/Hide Understanding Complexity Level)

Understanding Complexity Level

Complexity Level (CL) is a way to measure how complicated a routine (or function) is. It counts the number of decision points in the code—such as if and else statements.

The more decisions your code makes, the more complex it becomes. A higher complexity score usually means the code is harder to read, test, and maintain.

How is the Complexity Level Calculated?

Every routine starts with a complexity of 0. Then:

Each if and else, etc. adds to the score.
More nested logic (deeply indented blocks) increases the score even more.

Example:

routine check_value (num) if num > 10 then print "High" else print "Low" end if end routine

This routine has CL = 2 (+1 for the if statement).

What to Do If Complexity is Too High?

If a routine’s Complexity Level is high (21+ or more), the code is getting difficult to read, test, and maintain.

Ways to Reduce Complexity

Split large routines into smaller ones using local routines

Move parts of the logic into separate local routines. Each routine should focus on one task only.
Avoid Deep Nesting

Instead of many nested if statements, use early exits (guard statements). This makes the code flatter and easier to follow.
Use case Instead of Multiple if Statements

Before:

if code = "A" then print "Alpha" else if code = "B" then print "Beta" else if code = "C" then print "Gamma" else print "Unknown" end if

After (Simplified with case):

select case code case "A" print "Alpha" case "B" print "Beta" case "C" print "Gamma" case else print "Unknown" end select

The CL is now lower! The code is easier to follow.
Remove Unnecessary Logic

If logic isn’t needed, remove it! If an if statement always leads to return, rewrite it more cleanly.

Summary

The Complexity Level counts decision points (if, else, etc.).
Lower complexity means easier-to-read, test, and maintain code.
Reduce complexity by splitting routines into smaller local routines, avoiding deep nesting, using select case, and keeping logic simple.

Tip: If a routine’s Cl is 21+, break it into smaller local routines whenever possible! This will reduce its long term Technicl Debt.

0-10: Simple (Good)
11-20: Moderate (Review for improvement)
21+: Critical (Refactoring needed)

The report assigns a Lines of Code (Adjusted) status to each routine:

1-30: Simple (Good)
31-90: Moderate (Review for improvement)
91+: Critical (Refactoring needed)

The report assigns a Literals Usage status to each routine:

1-15: Minimal (Good)
16-30: Moderate (Consider refactoring)
31+: Excessive (Refactoring needed)

Example Insights Report

Below is a sample output from the Option Insights report.

-------------------------------- SheerPower Insights Report Program: example.spsrc -------------------------------- Total Lines: 1024 Routines: 38 Variables: 217 Max Complexity: 31 (Routine: process_data) Routine Complexity Summary: - process_data() [31] **Critical** - compute_stats() [22] **Moderate** - log_event() [8] **Good** Top 3 Literal Usages: - "Error: Invalid ID" (23 occurrences) - "Success" (15 occurrences) - "Data Updated" (9 occurrences) Optimization Suggestions: - Reduce nested loops in process_data() - Extract constants for common literals

Best Practices

To make the most of Option Insights, consider the following best practices:

Regularly check complexity scores during code development.
Refactor high-complexity routines to improve maintainability.
Use named constants for frequently repeated literals.
Minimize deep nesting in logic-heavy functions.
Review the report periodically to ensure code quality.

Conclusion

SheerPower's option insights provides a valuable way to assess and optimize code complexity. By reviewing the generated report and applying best practices, developers can maintain clean, efficient, and scalable SheerPower applications.

Hide Description

a$ b$ x y

Enter or modify the code below, and then click on RUN

Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use.

Understanding SheerPower's Option Insights Feature

Enabling Option Insights

Generated Report

Interpreting the Scores

Understanding Complexity Level

How is the Complexity Level Calculated?

What to Do If Complexity is Too High?

Ways to Reduce Complexity

Split large routines into smaller ones using `local routines`

Avoid Deep Nesting

Use `case` Instead of Multiple `if` Statements

Remove Unnecessary Logic

Summary

Example Insights Report

Best Practices

Conclusion

Enter or modify the code below, and then click on RUN

Understanding SheerPower's Option Insights Feature

Enabling Option Insights

Generated Report

Interpreting the Scores

Understanding Complexity Level

How is the Complexity Level Calculated?

What to Do If Complexity is Too High?

Ways to Reduce Complexity

Split large routines into smaller ones using local routines

Avoid Deep Nesting

Use case Instead of Multiple if Statements

Remove Unnecessary Logic

Summary

Example Insights Report

Best Practices

Conclusion

Enter or modify the code below, and then click on RUN

Split large routines into smaller ones using `local routines`

Use `case` Instead of Multiple `if` Statements