Sonargraph User Manual

Version 13.3.0

Table of Contents

1. Motivation for Code Quality

2. Getting Started

3. Licensing

3.1. Getting an Activation Code or a License
3.2. Activation Code Based Licensing
3.3. Proxy Settings
3.4. License Server Settings

4. Initial Configuration

4.1. Installation and Updates
4.2. Help
4.3. Editor Preferences
4.4. License Server Preferences
4.5. Proxy Preferences
4.6. Update Site Preferences
4.7. C/C++ Compiler Definitions
4.8. Search Path Configuration
4.9. C/C++ Parser Daemon Configurations
4.10. C# Configuration
4.11. Python Configuration

5. Getting Familiar with the Sonargraph System Model

5.1. Physical File Structure

5.2. Language Independent Model

5.3. Language Specific Models

5.3.1. Java/Kotlin Model
5.3.2. Kotlin Specific Issues
5.3.3. C++ Model
5.3.4. C# Model
5.3.5. Python Model

5.4. Logical Models

5.4.1. System-Based Logical Model
5.4.2. Module-Based Logical Model

6. Creating a System

6.1. Creating a Java System

6.2. Creating a C# System

6.3. Creating C/C++ Systems

6.4. Quality Model

6.4.1. Importing a Quality Model
6.4.2. Exporting a Quality Model

7. Adding Content to a System

7.1. Creating or Importing a Java Module

7.1.1. Importing Java Modules Using an Eclipse Workspace
7.1.2. Import Modules using the Sonargraph Gradle Plugin
7.1.3. Import Modules using the Sonargraph Maven Plugin
7.1.4. Importing Java Modules Using a Bazel Workspace
7.1.5. Import Modules Using the Build Unit(s) Importer
7.1.6. Creating a Java Module Manually

7.2. Creating or Importing a C++ Module

7.2.1. Importing C++ Modules from Visual Studio Files
7.2.2. Importing C++ Modules Via CMake or CCSpy
7.2.3. Creating a C++ Module Manually
7.2.4. C/C++ Module Configuration

7.3. Creating or Importing a C# Module

7.3.1. Importing C# Modules Using a Visual Studio Solution File

8. Interacting with a System

8.1. User Interface Components

8.1.1. Menu Bar
8.1.2. Tool Bar
8.1.3. Notifications Bar
8.1.4. Tables

8.2. Common Interaction Patterns

8.2.1. Special Graphic Elements Decorations

8.3. Sonargraph Workbench

8.3.1. Auxiliary Views

8.4. Getting a Quick Impression

8.5. Navigating through the System Components

8.6. Exploring the System Namespaces

8.7. Managing the System Files

8.8. Managing the Workspace

8.8.1. Definition of Filters, Modules and Root Directories
8.8.2. Managing Module Dependencies
8.8.3. Creating Workspace Profiles for Build Environments

8.9. Analyzer Execution Level

8.10. Analyzing Cycles

8.10.1. Revising Cycle Groups
8.10.2. Inspecting Cyclic Elements
8.10.3. Breaking Up Cycles

8.11. Exploring the System

8.11.1. Exploration View
8.11.2. Graph View
8.11.3. Treemap-Based System Exploration
8.11.4. Tabular System Exploration

8.12. Searching Elements

8.12.1. Searching Elements in Views

8.13. Detecting Duplicate Code

8.13.1. Configuration of Duplicate Code Blocks Computation

8.14. Examining the Source Code

8.14.1. Interaction with Auxiliary Views

8.15. Examining Metrics Results

8.16. Analyzing C++ Include Dependencies

8.17. Creating a Report

9. Handling Detected Issues

9.1. Using Virtual Models for Resolutions

9.2. Examining Issues

9.2.1. Identifying the Most Relevant Issues to Fix
9.2.2. Identifying Issue Hotspots

9.3. Ignoring Issues

9.4. Defining Fix and TODO Tasks

9.5. Editing Resolutions

9.6. Details about Sonargraph's Resolution Matching

10. Simulating Refactorings

10.1. Creating Delete Refactorings
10.2. Creating Move/Rename Refactorings
10.3. Managing Refactorings
10.4. Best Practices

11. Defining an Architecture

11.1. Models, Components and Artifacts

11.1.1. Using other criteria to assign components to artifacts
11.1.2. List of predefined attribute retrievers

11.2. Interfaces and Connectors

11.3. Reusing Architecture Aspects

11.4. Extending Aspect Based Artifacts

11.5. Extending Interfaces or Connectors

11.6. Adding Transitive or Deprecated Connections

11.7. Restricting Dependency Types

11.8. Connecting Complex Artifacts

11.9. Introducing Connection Schemes

11.10. Artifact Classes

11.11. How to Organize your Code

11.12. Designing Generic Architectures Using Templates

11.12.1. Using unrestricted generated artifacts
11.12.2. Using connection schemes to regulate accessibility

11.13. Best Practices

11.14. Architecture DSL Language Specification

12. Visualizing Architecture Aspects

13. Interactive Restructuring and Code Organization

13.1. Assigning Elements to Artifacts

14. Examining Changes

15. Defining Quality Gates

15.1. Creating Quality Gates
15.2. Using Quality Gates in the Continuous Integration (CI) Build
15.3. Current Quality Gate Limitations

16. Extending the Static Analysis

16.1. Interaction with Auxiliary Views

16.2. Groovy Scripts from Quality Model

16.3. Creating a new Groovy Script

16.3.1. Default Parameters in a Script
16.3.2. Adding Parameters
16.3.3. Creating Run Configurations

16.4. Editing a Groovy Script

16.4.1. Auto Completion
16.4.2. Compiling a Groovy Script

16.5. Producing Results with Groovy Scripts

16.6. Running a Groovy Script Automatically

16.7. Managing Groovy Scripts

16.8. Groovy Script Best Practices

16.8.1. Only Visit What is Needed
16.8.2. Find Text in Code

17. Using Additional Plugins

17.1. Plugin Configuration
17.2. Spring Microservices Plugin
17.3. Swagger Plugin
17.4. SpotBugs Plugin
17.5. PMD Plugin
17.6. Issues Importer Plugin

18. Investigating Microservice Dependencies

19. Build Server Integration

20. IDE Integration

20.1. Eclipse Plugin

20.1.1. Assigning a System
20.1.2. Displaying Issues and Tasks
20.1.3. Suspending / Resuming Quality Monitoring
20.1.4. Setting Analyzer Execution Level
20.1.5. Getting Back In Sync with Manual Refresh
20.1.6. Examining Changes
20.1.7. Execute Refactorings in Eclipse

20.2. IntelliJ Plugin

20.2.1. Assigning a System
20.2.2. Displaying Issues and Tasks
20.2.3. Toolbar
20.2.4. Getting Back In Sync with Manual Refresh
20.2.5. Examining Changes
20.2.6. Execute Refactorings in IntelliJ

20.3. Collaboration between Sonargraph and IDE

21. Metric Definitions

21.1. Language Independent Metrics
21.2. Java Metrics
21.3. C# Metrics
21.4. C,C++ Metrics
21.5. Python Metrics

22. How to Resolve Issues

22.1. Language Independent Issues
22.2. Java Specific Issues
22.3. C# Specific Issues
22.4. C/C++ Specific Issues

23. FAQ

23.1. Out Of Memory Exceptions
23.2. Groovy Template
23.3. MSBuild Error (MSB4019) during Analysis of Visual Studio C# Project

24. References

25. Trademark Attributions, Library License Texts, and Source Code

26. Legal Notice

Glossary

1. Walk Through Tutorial (Java)

1.1. Workspace Definition
1.2. Basic Analysis
1.3. Advanced Analysis
1.4. Architecture: Artifacts, Aspects Files and Standard Connections
1.5. Architecture: Explicit Interfaces and Connectors
1.6. Architecture: Advanced Connections
1.7. Architecture: Advanced Aspect Files
1.8. Architecture: Referencing external Artifacts in Aspect Files
1.9. Headless Check with Sonargraph-Build
1.10. Check at Development Time with Sonargraph Eclipse Integration

2. Tutorial - Java

2.1. Setup the Software System

2.1.1. Create a new Software System
2.1.2. Define the Workspace
2.1.3. Define Module Dependencies
2.1.4. Parse the Workspace

2.2. Initial Analysis

2.2.1. Detect Problems Using Standard Metrics
2.2.2. Adjust Metric Thresholds

2.3. Problem Analysis

2.3.1. Examine Cycles
2.3.2. Examine Duplicate Code
2.3.3. Handle Issues

2.4. Detailed Dependency Analysis

2.4.1. Explore Dependencies
2.4.2. Check how Elements are Connected via Graph View
2.4.3. Check how Elements are Connected via the Dependencies View
2.4.4. Search for Elements

2.5. Advanced Analysis With Scripts

2.5.1. Create a New Script
2.5.2. Execute Existing Script

2.6. Share Results

2.6.1. Work with Snapshots
2.6.2. Define Quality Standards using Quality Models
2.6.3. Export to Excel

3. Tutorial - C#

3.1. Setup the Software System
3.2. Further Steps

4. Tutorial - C++

4.1. Setup the Software System - Compiler Definitions
4.2. Setup the Software System - Capture Compile Commands with ccspy
4.3. Setup the Software System - Visual Studio Import
4.4. Further Steps

5. Sonargraph Script API Documentation

Index

List of Figures

1.1. Visualizing Defined Architecture and Existing Dependencies in the Architectural View
1.2. To Avoid: "Big Ball of Mud" Dependency Structure
1.3. Sonargraph Products
2.1. Exploration View
4.1. Editor Preferences
4.2. License Server Preferences
4.3. Proxy Preferences
4.4. Update Site Preferences
4.5. C++ Compiler Definition
4.6. Search Path Configuration
5.1. Physical File Structure
5.2. System Domain Model
5.3. Java Domain Model
5.4. C++ Domain Model
5.5. C# Domain Model
5.6. Physical Namespaces
5.7. Logical Namespaces
5.8. System-Based Logical Model
5.9. Module-based Logical Model
6.1. Marking root directories from JSON file
6.2. Naming modules for root directories from JSON file
6.3. New System with Quality Model
6.4. Import Quality Model
6.5. Export Quality Model
7.1. Importing Java Modules Using an Eclipse workspace
7.2. Importing Java Modules Using a Bazel workspace
7.3. Manage Root Directory Path
7.4. Create C/C++ System Based on Solution File Import
7.5. C/C++ Module Configuration
8.1. Tool Bar
8.2. Notifications Bar
8.3. Table with activated text filter
8.4. Sonargraph Workbench
8.5. System View
8.6. Navigation View
8.7. Namespaces View
8.8. Logical Model Selection
8.9. Files View
8.10. Workspace View
8.11. Defining a Manual Workspace Dependency
8.12. Defining a Manual Workspace Dependency
8.13. Creating Workspace Profile
8.14. Analyzers View
8.15. Cycle Groups View
8.16. Cycle View
8.17. Cycle Group shown in Exploration View
8.18. Cycle Breakup View
8.19. Highlighted Added Cyclic Elements
8.20. Example of Created Exploration View without Focus
8.21. Exploration View with Applied Focus
8.22. Exploration View created from Architecture Aspect showing the Levelization Mode Widget
8.23. Focus Dialog
8.24. Add to Focus Dialog
8.25. Graph View
8.26. Quick View Creation
8.27. Advanced View Creation Dialog
8.28. Focus Toolbar
8.29. Focus Dropdown Menu
8.30. Advanced Focus Dialog
8.31. Semantics of Colors
8.32. Architecture Independent Dependencies
8.33. Levels in Graph View
8.34. On Demand Cycle Groups
8.35. On Demand Cycle Groups
8.36. Underlying Parser Dependencies for Edge
8.37. Incoming and Outgoing Parser Dependencies
8.38. Context Menu Interactions
8.39. Show Type-based Graph view
8.40. Type-based Graph
8.41. View Options
8.42. Treemap 2D View
8.43. Treemap 3D View
8.44. Treemap Configuration
8.45. Treemap configuration 3D
8.46. Treemap Issue Collector
8.47. Treemap Info View
8.48. Multi-Selection in Treemap Info View
8.49. Dependencies View
8.50. Drilling Down Dependencies
8.51. Interaction with Auxiliary Views
8.52. Context Menu Interactions
8.53. Standard Search Dialog
8.54. Search Dialog to Locate Members
8.55. Text Search in Views
8.56. Duplicate Blocks View
8.57. Duplicates Source View
8.58. Source View
8.59. Hyperlinking and Find Text Features in Source View
8.60. Metrics View
8.61. Metrics Histogram
8.62. Element Metrics View
8.63. Metric Thresholds Configuration
8.64. C++ Include Dependency View
8.65. Table Filter Options in HTML Report
9.1. Virtual Models
9.2. Issues View
9.3. Filter Issues
9.4. Ranking of Issues
9.5. Issue Hotspots Treemap Visualization
9.6. Ignore View
9.7. Resolution Dialog
10.1. Refactorings View
11.1. Architecture View
11.2. Architecture of the order management micro service
11.3. Layering of a subsystem
12.1. DSL Example
12.2. Generate UML Component Diagram
12.3. UML Component Diagram
12.4. Cross-check the JDBC Component
12.5. Cross-check the License Component
13.1. Artifact Filter
14.1. System Diff View (Issues)
14.2. System Diff View (Cycle Groups)
14.3. HTML Diff Report
15.1. Quality Gate View
15.2. Current System Condition Dialog
15.3. Baseline Issue Condition Dialog
15.4. Baseline Metric Condition Dialog
15.5. Exclude Filter Dialog
16.1. Script View
16.2. Quality Model
16.3. New Script
16.4. Parameter Definition
16.5. Parameter Usage in Script
16.6. Create Run Configuration
16.7. Auto Completion
16.8. Script View Marker
16.9. Script View Marker Tooltip
16.10. Script View Elements Tab
16.11. Script View Tree Tab
16.12. Script View Issues Preview
16.13. Script View Metrics Preview
16.14. Script Runner
17.1. Spring Microservices Plugin Web Call (above) and Web Resource (below)
17.2. Architecture Violations for Dependencies between Plugin Elements
18.1. Exploring Microservice Dependencies
20.1. Status Icon
20.2. Open Sonargraph System
20.3. Show Issues in Problems View
20.4. Problems View Configuration for Sonargraph Issues
20.5. Context Menu To Open Sonargraph Cycle Groups View
20.6. Sonargraph Issues in Eclipse with Baseline Applied
20.7. Open Sonargraph System
20.8. Sonargraph Tool Window
20.9. Sonargraph Issues in IntelliJ with Baseline Applied
20.10. Fixing a Detected Issue in the IDE
20.11. Selecting Elements for Inspection in Sonargraph
2.1. New Manual System Wizard
2.2. Root Directories Dialog
2.3. Workspace View
2.4. Workspace View After Parsing
2.5. Metrics View
2.6. Metrics View Highlighting Thresholds Violations
2.7. Filter Issues
2.8. Cycle Groups View
2.9. Cycle View
2.10. Duplicate Code Blocks View
2.11. Duplicate Source View
2.12. Add TODO Issue
2.13. Resolutions View
2.14. Open in Exploration View
2.15. Exploration View Drilldown
2.16. Exploration View Interactions
2.17. Graph View
2.18. Graph View Interactions
2.19. Dependencies View
2.20. Create a New Script
2.21. Execute a Script
2.22. Export Metrics to Excel Context Menu
3.1. System based on C# Visual Studio Solution File
3.2. Select C# Solution File, Configuration and Platform
3.3. Select C# Solution File, Configuration and Platform
4.1. Specify Visual Studio Solution File
4.2. MSBuild Exception
4.3. Parse Error (Missing Header File)