Intro
Background: Sokrates Philosophy
"Know your code! The unexamined code is not worth maintaining." Sokrates helps you understand your code by making visible the size, complexity, and coupling of software.Using Sokrates
You can use Sokrates in four modes: the analyze and reflect mode, the interactive explorations mode, the traffic lights mode, the software architecture documentation modeBegin With the End in Mind: Sokrates Reports
Before we zoom into the details of Sokrates, let's first see what insights Sokrates can give you. Sokrates makes visible the size, complexity, and coupling of software. More specifically, Sokrates generates several views on your source code, describing the overall source code characteristics, duplication, components, dependencies, conditional complexity, etc.Get Your Hands Dirty
To learn how to use Sokrates, like with any software tools or programming languages, you need to do some hands-on work. Install Sokrates, and use this to analyze your code.Configuring and Scoping
Sokrates Configuration File
Sokrates analyses take two inputs: the actual source code, including all folders and files, and a configuration file, which describes how Sokrates should view and analyze the source code.Scoping
Scoping defines which parts of source code you want to analyze in detail and which parts to ignore. The code that developers wrote manually is the most important. It contains critical content for understanding the system's unique structure, logic, and team's design decisions.Logical Decompositions
Logical decomposition is a view on the organization of the main source code. In a logical decomposition, you define components and rules to include files in the components so that each file ends in exactly one component.Concerns
Concerns are any aspects of a software system that can be identified thourgh patterns in code.Sokrates' System Analyses
Sokrates Analysis Overview
Sokrates processes source code in multiple stages, some of which are optional. The analysis starts with scoping, continuing through an examination of individual files and units, ending with an aggregation of results and export of reports.Code Cleaning
As the first step in its analysis, Sokrates cleans the code to simplify analyses and to improve their reliability. Cleaning includes removal of comments, empty lines, and long string constants.File-Level Measurements: File Size
Sokrates measures the size of the file in lines of code, ignoring empty lines and comments.File-Level Measurements: File Age Analysis
File history analysis takes as an input the list of dates on which source code files changes and studies these dates to understand how frequently developers have changed the files, how old the files are, and how recently developers have updated them.File-Level Measurements: File Change Frequency Analysis
File history analysis takes as an input the list of dates on which source code files changes and studies these dates to understand how frequently developers have changed the files, how old the files are, and how recently developers have updated them.File-Level Measurements: Temporal Dependencies Analysis
File history analysis takes as an input the list of dates on which source code files changes and studies these dates to understand how frequently developers have changed the files, how old the files are, and how recently developers have updated them.File-Level Measurements: Temporal Dependencies Analysis
File history analysis takes as an input the list of dates on which source code files changes and studies these dates to understand how frequently developers have changed the files, how old the files are, and how recently developers have updated them.Unit-Level Measurements
Depending on a language, a unit can be a method, function procedure. Sokrates measures two things about each unit: size and conditional complexity.Duplication Analysis
For duplication, Sokrates look at places in code where there are six or more lines of code that are the same.Finding Dependencies based on Text Patterns
Sokrates analyses dependencies through simple text patterns searches.Finding Dependencies through Duplication and Change History
Sokrates introduces two additional dependency measurements: dependency based on duplication between files and dependencies based on the history of file changes.Aggregating Measurements
Sokrates performs aggregation at three levels: the overall project level, the file type level (based on file extension), and the logical decomposition level.Metrics Table
The metrics table is a list of name-value pairs, a linearized list of all Sokrates aggregated measurements. Sokrates employs the metrics table to define goals and controls and in trend analyses.Controls
In Sokrates, you can define traffic lights like controls. For each of the metrics that Sokrates measures, you can specify a monitor with the threshold and tolerance. Sokrates will then generate a report labeling each control with one of the following states. OK (green) means that the measured value is below the threshold. Tolerant (yellow) means that the measured value is above the threshold but within the tolerance range. Failed (red) means that the measured value is above the threshold and the tolerance level.Trend Analysis
Trend analysis shows the difference between values measured at different times, comparing the results of the current analysis with previous reports.Landscape Analysis
Landscape Analysis Overview
The Sokrates landscape analysis aggregates and indexes the Sokrates project analysis reports, providing a centralized and uniform view on multiple Sokrates projects.Appendixes
Appendix: Regular Expressions
You cannot efficiently use Sokrates if you do not know at least the basics of regular expressions. Sokrates uses regular expressions for two purposes: to filter and classify files, extract and manipulate text, name components, or identify dependencies.Appendix: Sokrates String Transformation Language (SSTL)
The Sokrates String Transformation Language (SSTL) is a simple embedded programming language enabling you to transform a phrase extracted from a file path or file content into another string. You can use SSTL to define the names of components and identify dependencies among the components.Appendix: Installation
You can install and run Sokrates in three ways. First, you can download the Sokrates command-line interface JAR file. Second, you can download the Sokrates Explorer JAR file. Lastly, you can build it from scratch from the Sokrates' GitHub repository.Appendix: Sokrates Configuration File
Sokrates configuration is a JSON file. You can use create this file manually from scratch, or use the init command to generate a default file for your project.Appendix: Command Line Interface (CLI)
Sokrates command-line interface (CLI) includes five commands: init, generateReports, updateConfig, initLandscape, and updateLandscape.Appendix: Sokrates Explorer
Sokrates Explorer centralizes configuration, running of commands, and preview of analysis results in one tool. Explorer has a graphical user interface with a configuration editor, code preview panels, and several additional features that facilitate free exploration of code. With Explorer, you can almost instantly see how a change in a setting, e.g., adding a new rule for detecting test files, impacts the analysis results.