Sonargraph User Manual

Version 11.5.0


Table of Contents
1. Motivation for Code Quality
2. Licensing
2.1. Getting an Activation Code or a License
2.2. Activation Code Based Licensing
2.3. Proxy Settings
2.4. License Server Settings
3. Getting Started
3.1. Installation and Updates
3.2. Help
3.3. Editor Preferences
3.4. License Server Preferences
3.5. Proxy Preferences
3.6. Update Site Preferences
3.7. C/C++ Compiler Definitions
3.8. C# Configuration
3.8.1. C# Build Executor Configuration
3.9. Search Path Configuration
3.10. Python Configuration
4. Getting Familiar with the Sonargraph System Model
4.1. Physical File Structure
4.2. Language Independent Model
4.3. Language Specific Models
4.3.1. Java/Kotlin Model
4.3.2. Kotlin Specific Issues
4.3.3. C++ Model
4.3.4. C# Model
4.3.5. Python Model
4.4. Logical Models
4.4.1. System-Based Logical Model
4.4.2. Module-Based Logical Model
5. Creating a System
5.1. Creating a Java System
5.2. Creating a C# System
5.3. Creating C/C++ Systems
5.4. Quality Model
5.4.1. Importing a Quality Model
5.4.2. Exporting a Quality Model
6. Adding Content to a System
6.1. Creating or Importing a Java Module
6.1.1. Importing Java Modules Using an Eclipse Workspace
6.1.2. Importing Java Modules from IntelliJ
6.1.3. Importing Java Modules from Maven POM File
6.1.4. Importing Java Modules Using a Bazel Workspace
6.1.5. Creating a Java Module Manually
6.2. Creating or Importing a C++ Module
6.2.1. Importing C++ Modules from Visual Studio Files
6.2.2. Importing C++ Modules Using Make Command Capturing Files
6.2.3. Creating a C++ Module Manually
6.2.4. C/C++ Module Configuration
6.3. Creating or Importing a C# Module
6.3.1. Importing C# Modules Using a Visual Studio Project File
6.3.2. Importing C# Modules Using a Visual Studio Solution File
6.3.3. Creating a C# Module Manually
6.3.4. C# Module Configuration
6.3.5. C# MSBuild Configuration
7. Interacting with a System
7.1. User Interface Components
7.1.1. Menu Bar
7.1.2. Tool Bar
7.1.3. Notifications Bar
7.1.4. Tables
7.2. Common Interaction Patterns
7.2.1. Special Graphic Elements Decorations
7.3. Sonargraph Workbench
7.4. Navigating through the System Components
7.5. Exploring the System Namespaces
7.6. Managing the System Files
7.7. Managing the Workspace
7.7.1. Definition of Filters, Modules and Root Directories
7.7.2. Managing Module Dependencies
7.7.3. Creating Workspace Profiles for Build Environments
7.8. Analyzer Execution Level
7.9. Analyzing Cycles
7.9.1. Revising Cycle Groups
7.9.2. Inspecting Cyclic Elements
7.9.3. Breaking Up Cycles
7.10. Exploring the System
7.10.1. Concepts for System Exploration
7.10.2. Tree Based System Exploration
7.10.3. Graph-Based System Exploration
7.10.4. Treemap-Based System Exploration
7.10.5. Tabular System Exploration
7.11. Searching Elements
7.11.1. Searching Elements in Views
7.12. Detecting Duplicate Code
7.12.1. Configuration of Duplicate Code Blocks Computation
7.13. Examining the Source Code
7.13.1. Interaction with Auxiliary Views
7.14. Examining Metrics Results
7.15. Analyzing C++ Include Dependencies
7.16. Creating a Report
8. Handling Detected Issues
8.1. Using Virtual Models for Resolutions
8.2. Examining Issues
8.2.1. Identifying the Most Relevant Issues to Fix
8.2.2. Identifying Issue Hotspots
8.3. Ignoring Issues
8.4. Defining Fix and TODO Tasks
8.5. Editing Resolutions
8.6. Details about Sonargraph's Resolution Matching
9. Simulating Refactorings
9.1. Creating Delete Refactorings
9.2. Creating Move/Rename Refactorings
9.3. Managing Refactorings
9.4. Best Practices
10. Defining an Architecture
10.1. Models, Components and Artifacts
10.1.1. Using other criteria to assign components to artifacts
10.1.2. List of predefined attribute retrievers
10.2. Interfaces and Connectors
10.3. Reusing Architecture Aspects
10.4. Extending Aspect Based Artifacts
10.5. Extending Interfaces or Connectors
10.6. Adding Transitive Connections
10.7. Restricting Dependency Types
10.8. Connecting Complex Artifacts
10.9. Introducing Connection Schemes
10.10. Artifact Classes
10.11. How to Organize your Code
10.12. Designing Generic Architectures Using Templates
10.12.1. Using unrestricted generated artifacts
10.12.2. Using connection schemes to regulate accessibility
10.13. Best Practices
10.14. Architecture DSL Language Specification
11. Visualizing Architecture Aspects
12. Interactive Restructuring and Code Organization
12.1. Architectural View
12.2. Assigning Elements to Artifacts
13. Examining Changes
14. Defining Quality Gates
14.1. Creating Quality Gates
14.2. Using Quality Gates in the Continuous Integration (CI) Build
14.3. Current Quality Gate Limitations
15. Extending the Static Analysis
15.1. Interaction with Auxiliary Views
15.2. Groovy Scripts from Quality Model
15.3. Creating a new Groovy Script
15.3.1. Default Parameters in a Script
15.3.2. Adding Parameters
15.3.3. Creating Run Configurations
15.4. Editing a Groovy Script
15.4.1. Auto Completion
15.4.2. Compiling a Groovy Script
15.5. Producing Results with Groovy Scripts
15.6. Running a Groovy Script Automatically
15.7. Managing Groovy Scripts
15.8. Groovy Script Best Practices
15.8.1. Only Visit What is Needed
15.8.2. Find Text in Code
16. Using Additional Plugins
16.1. Plugin Configuration
16.2. Spring Microservices Plugin
16.3. Swagger Plugin
16.4. SpotBugs Plugin
16.5. PMD Plugin
17. Investigating Microservice Dependencies
18. Build Server Integration
19. IDE Integration
19.1. Eclipse Plugin
19.1.1. Assigning a System
19.1.2. Displaying Issues and Tasks
19.1.3. Suspending / Resuming Quality Monitoring
19.1.4. Setting Analyzer Execution Level
19.1.5. Getting Back In Sync with Manual Refresh
19.1.6. Examining Changes
19.1.7. Execute Refactorings in Eclipse
19.2. IntelliJ Plugin
19.2.1. Assigning a System
19.2.2. Displaying Issues and Tasks
19.2.3. Toolbar
19.2.4. Getting Back In Sync with Manual Refresh
19.2.5. Examining Changes
19.2.6. Execute Refactorings in IntelliJ
19.3. Collaboration between Sonargraph and IDE
20. Metric Definitions
20.1. Language Independent Metrics
20.2. Java Metrics
20.3. C# Metrics
20.4. C/C++ Metrics
20.5. Python Metrics
21. How to Resolve Issues
21.1. Language Independent Issues
21.2. Java Specific Issues
21.3. C# Specific Issues
21.4. C/C++ Specific Issues
22. FAQ
22.1. Out Of Memory Exceptions
22.2. Groovy Template
22.3. MSBuild Error (MSB4019) during Analysis of Visual Studio C# Project
23. References
24. Trademark Attributions, Library License Texts, and Source Code
25. 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 - Makefile Capturing
4.3. Setup the Software System - Visual Studio Import
4.4. Further Steps
5. Sonargraph Script API Documentation
Index
List of Figures
1.1. To Avoid: "Big Ball of Mud" Dependency Structure
1.2. Sonargraph Products
3.1. Editor Preferences
3.2. License Server Preferences
3.3. Proxy Preferences
3.4. Update Site Preferences
3.5. C++ Compiler Definition
3.6. C# Profiles Configuration
3.7. C# Build Executor
3.8. Search Path Configuration
4.1. Physical File Structure
4.2. System Domain Model
4.3. Java Domain Model
4.4. C++ Domain Model
4.5. C# Domain Model
4.6. Physical Namespaces
4.7. Logical Namespaces
4.8. System-Based Logical Model
4.9. Module-based Logical Model
5.1. Marking root directories from JSON file
5.2. Naming modules for root directories from JSON file
5.3. New System with Quality Model
5.4. Import Quality Model
5.5. Export Quality Model
6.1. Importing Java Modules Using an Eclipse workspace
6.2. Importing Java Modules from IntelliJ
6.3. Importing Java Maven Modules
6.4. Importing Java Modules Using a Bazel workspace
6.5. Manage Root Directory Path
6.6. Create C/C++ System Based on Solution File Import
6.7. C/C++ Module Configuration
6.8. Missing C# Assemblies
6.9. C# Module Configuration
6.10. Locate Missing C# Assemblies
6.11. Configuration of MSBuild
6.12. Setting the MSBuild Verbosity Level in Visual Studio
7.1. Tool Bar
7.2. Notifications Bar
7.3. Table with activated text filter
7.4. Sonargraph Workbench
7.5. Navigation View
7.6. Namespaces View
7.7. Logical Model Selection
7.8. Files View
7.9. Workspace View
7.10. Defining a Manual Workspace Dependency
7.11. Defining a Manual Workspace Dependency
7.12. Creating Workspace Profile
7.13. Analyzers View
7.14. Cycle Groups View
7.15. Cycle View
7.16. Cycle Group shown in Exploration View
7.17. Cycle Breakup View
7.18. Highlighted Added Cyclic Elements
7.19. Quick View Creation
7.20. Quick View Creation
7.21. Focus Toolbar
7.22. Focus Dropdown Menu
7.23. Advanced Focus Dialog
7.24. Semantics of Colors
7.25. Architecture Independent Dependencies
7.26. Exploration View
7.27. Before and After Drilldown
7.28. Sample Exploration view
7.29. Extend Focus Menu
7.30. Extend Focus Result
7.31. Sample Exploration view
7.32. Extend Focus Menu
7.33. Underlying Parser Dependencies for Arc
7.34. Incoming and Outgoing Parser Dependencies
7.35. View option synchronization
7.36. Expand Dependency to Component Level
7.37. Context Menu Interactions
7.38. View Options
7.39. Graph View
7.40. Levels in Graph View
7.41. On Demand Cycle Groups
7.42. On Demand Cycle Groups
7.43. Underlying Parser Dependencies for Edge
7.44. Incoming and Outgoing Parser Dependencies
7.45. View option synchronization
7.46. Context Menu Interactions
7.47. Show Type-based Graph view
7.48. Type-based Graph
7.49. View Options
7.50. Treemap 2D View
7.51. Treemap 3D View
7.52. Treemap configuration
7.53. Treemap configuration 3D
7.54. Treemap Issue Collector
7.55. Dependencies View
7.56. Drilling Down Dependencies
7.57. Interaction with Auxiliary Views
7.58. Context Menu Interactions
7.59. Standard Search Dialog
7.60. Search Dialog to Locate Members
7.61. Text Search in Views
7.62. Duplicate Blocks View
7.63. Duplicates Source View
7.64. Source View
7.65. Hyperlinking and Find Text Features in Source View
7.66. Show Only Violations
7.67. Metrics View
7.68. Metrics Histogram
7.69. Element Metrics View
7.70. Metric Thresholds Configuration
7.71. C++ Include Dependency View
7.72. Table Filter Options in HTML Report
8.1. Virtual Models
8.2. Issues View
8.3. Filter Issues
8.4. Ranking of Issues
8.5. Issue Hotspots Treemap Visualization
8.6. Ignore View
8.7. Resolution Dialog
9.1. Refactorings View
10.1. Architecture View
10.2. Architecture of the order management micro service
10.3. Layering of a subsystem
11.1. DSL Example
11.2. Generate UML Component Diagram
11.3. UML Component Diagram
11.4. Cross-check the JDBC Component
11.5. Cross-check the License Component
12.1. Architectural view
12.2. Artifact Filter
13.1. System Diff View (Issues)
13.2. System Diff View (Cycle Groups)
13.3. HTML Diff Report
14.1. Quality Gate View
14.2. Current System Condition Dialog
14.3. Baseline Issue Condition Dialog
14.4. Baseline Metric Condition Dialog
14.5. Exclude Filter Dialog
15.1. Script View
15.2. Quality Model
15.3. New Script
15.4. Parameter Definition
15.5. Parameter Usage in Script
15.6. Create Run Configuration
15.7. Auto Completion
15.8. Script View Marker
15.9. Script View Marker Tooltip
15.10. Script View Elements Tab
15.11. Script View Tree Tab
15.12. Script View Issues Preview
15.13. Script View Metrics Preview
15.14. Script Runner
16.1. Plugin Manager Preference Page
16.2. Sonargraph Plugin Repository
16.3. Spring Microservices Plugin Web Call (above) and Web Resource (below)
16.4. Architecture Violations for Dependencies between Plugin Elements
17.1. Exploring Microservice Dependencies
19.1. Status Icon
19.2. Open Sonargraph System
19.3. Show Issues in Problems View
19.4. Problems View Configuration for Sonargraph Issues
19.5. Context Menu To Open Sonargraph Cycle Groups View
19.6. Sonargraph Issues in Eclipse with Baseline Applied
19.7. Open Sonargraph System
19.8. Sonargraph Tool Window
19.9. Sonargraph Issues in IntelliJ with Baseline Applied
19.10. Fixing a Detected Issue in the IDE
19.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. Select C++ Modules to Import from Capturing Files
4.2. Renaming and Configuring C++ Modules to Import from Capturing Files
4.3. Specify Visual Studio Solution File
4.4. MSBuild Exception
4.5. Parse Error (Missing Header File)