DevNotes_DevGuide_CodeSceneIntegration

[WIP] Code Scene Pull Request Integration

CodeScene is a code analysis tool that helps to identify technical debt in software projects, gives insights in how to improve the technical debt, and offers planning and integration tools to minimize technical debt in existing and future work.

CodeScene has two primary modes of operation; the first is to run weekly scans on a repository, and the second is to analyze pull requests to analyze new code. Currently, the weekly scans are run for sasview, sasdata, and sasmodels, with pull request integration to come in a phased manner

The weekly scan gives each project file a score out of ten based on the existing technical debt in the file. The summary page shows the average code health score, the average score for files with the highest development activity (Hotspots), and the worst performer. The summary also lists files recently improved and those that declined in health.

Pull request integration is an automated tool that analyzes new code submitted through pull requests. If the analysis finds a critical health issue, which are outlined below, the bot will give comments on each failing issue, and submit a review with changes requested.

Scoring System

Code Health is an aggregated metric based on 25+ factors scanned from the source code. The code health factors correlate with increased maintenance costs and an increased risk for defects. Code Health is a model that correlates measurable aspects of your code with positive or negative outcomes for your project.

https://codescene.com/product/code-health

Pull Request Integration Scheme

Pull request integration will be implemented in a staged process. Currently, sasdata is the only repository with any integration, setup using a configuration file in the repo, but every check is turned off to start.

Integration plan:

• Write an ADR on CodeScene usage and code health (In progress - https://github.com/orgs/SasView/discussions/3171#discussioncomment-14214525)
• Write a wiki outlining the errors associated with CodeScene and how to fix them (in progress - this wiki!)
• Add a codescene configuration file to every repo, with every check turned off (In progress - done for sasdata, todo for sasview and sasmodels)
• Enable the Minimal Safety Net for the sasdata repo
• Enable the Minimal Safety Net for all repos, and add the Quality Guardians checks to sasdata
• Enable the Quality Guardians checks to all repos and add the Elevate Code Health checks to sasdata
• Enable the Elevate Code Health checks to all repos
• Use project planning tools in CodeScene to improve code health in hot spots for all repos

Pull Request Blockers and How to Fix Them

Definitions:

• Module: Either an importable python module, or a class for the purpose of this wiki section.
• Function: Either a top-level, stand-alone function, or a class-level method.
• Variable: Any variable within a module or function as defined here.
• Element: A variable or function as defined here.

Thresholds:

• constructor_max_arguments
• file_lines_of_code_for_alert
• file_lines_of_code_for_critical_alert
• file_lines_of_code_for_warning
• file_mean_cyclomatic_complexity_warning
• function_bumpy_road_bumps_for_warning
• function_bumpy_road_nesting_level_depth
• function_complex_conditional_branches_alert
• function_complex_conditional_branches_warning
• function_cyclomatic_complexity_alert
• function_cyclomatic_complexity_warning
• function_lines_of_code_alert
• function_lines_of_code_warning
• function_max_arguments
• function_nesting_depth_warning

Coding Rules:

• Brain Method
• Bumpy Road Ahead
• Code Duplication
• Complex Conditional
• Complex Method
• Constructor Over-Injection
• Deep, Global Nested Complexity
• Deep, Nested Complexity
• Duplicated Assertion Blocks
• Excess Number of Function Arguments
• Global Conditionals
• Large Assertion Blocks
• Large Embedded Code Block
• Large Method
• Lines of Code in a Single File
• Lines of Declarations in a Single File
• Low Cohesion
• Missing Arguments Abstractions
• Number of Functions in a Single Module
• Overall Code Complexity
• Overall Function Size
• Primitive Obsession
• String Heavy Function Arguments

Code Violations:

• Low Cohesion
  • Indicates: A module has multiple unrelated tasks within a single module.
  • Why This Should Be Fixed: If elements in a module are unrelated, finding the logical element and debugging them will be more difficult for developers.
  • Likely Cause: Every call to a module should be related to all other calls to the module in some tangible way. If this is triggered, CodeScene thinks a module element is unrelated to all other elements.
  • How to Fix: Move the unrelated element(s) to its/their own module, or to an existing module that makes more sense.
  • Example Fix: https://github.com/SasView/sasview/pull/3535 - Moved many user-specific file handling methods into the user.py module to better enable developers in finding these methods.
• Brain Class (God Class)
  • Indicates: A module has a large set of related logic, but has grown large and some of that logic can likely be separated into multiple modules.
  • Why This Should Be Fixed: Large modules can be difficult to modify, extend, and debug.
  • Likely Cause: A module has multiple, related elements that could be easily separated from one another.
  • How to Fix: Create smaller modules for logical sub-modules and refer to those modules from the original God Class.
  • Example Fix: https://github.com/SasView/sasview/pull/3776 - The FittingWidget module once housed all fitting-related logic, making it difficult to change due to its enormity. The staged refactoring separated the God Class into a series of logical sub-widgets.
• Developer Congestion
  • Indicates: Multiple developers are working on the same code, which can lead to bottlenecks and conflicts.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Cyclomatic Complexity
  • Indicates: A high number of conditional statements in a function.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• DRY (Don't Repeat Yourself)
  • Indicates: Similar logic is duplicated in multiple places, and when one area is modified, the other also requires changes.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Primitive Obsession
  • Indicates: Basic types (e.g. str, float, int, etc.) are used to represent complex concepts (e.g. EmailAddress, Money, ZipCode, etc.)
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Large Method
  • Indicates: Modules with a large number of lines of code.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Nested Complexity
  • Indicates: Conditional statements within conditional statements, within conditional statements...
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Bumpy Road
  • Indicates: A function has with multiple if/else statements or for loops within it.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Complex Conditional
  • Indicates: An expression has multiple, branched logical operations within it.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Large Assertion Blocks
  • Indicates: A function has consecutive assert statements.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example:
• Duplicated Assertion Blocks
  • Indicates: Multiple functions have the same assert statements.
  • Why This Should Be Fixed:
  • Likely Cause:
  • How to Fix:
  • Example: