Lines of Code Metrics (SLOC, PLOC, LLOC, BLANK, CLOC)

Relevant source files

The following files were used as context for generating this wiki page:

• rust-code-analysis-book/src/developers/loc.md
• src/metrics/loc.rs
• rust-code-analysis-book/src/metrics.md
• src/spaces.rs
• src/metrics/mi.rs
• src/output/dump_metrics.rs

Lines of Code (LoC) metrics in rust-code-analysis provide quantitative measures of source code size and structure. These metrics serve as indicators of program complexity and maintainability by categorizing lines based on their content: actual instructions, comments, or whitespace.

The project implements these metrics through the Loc trait, which allows language-specific parsing of Abstract Syntax Tree (AST) nodes to identify statements and comment types. These metrics are fundamental to calculating more complex indices, such as the Maintainability Index (MI).
Sources: rust-code-analysis-book/src/developers/loc.md:1-5, src/metrics/loc.rs:1-10

Metric Definitions

The library distinguishes between five primary types of line metrics, each calculated using specific logic tailored to the target programming language.

Metric	Full Name	Description
SLOC	Source Lines of Code	A straight count of all lines in a file, including code, comments, and blank lines.
PLOC	Physical Lines of Code	A count of unique instruction lines. Includes brackets or syntax on new lines; excludes comments/blanks.
LLOC	Logical Lines of Code	A count of the number of statements in the code (e.g., function calls, assignments).
CLOC	Comment Lines of Code	A count of lines containing comments, regardless of type (single-line, block, or doc).
BLANK	Blank Lines	A count of the empty or whitespace-only lines present in the source code.

Sources: rust-code-analysis-book/src/developers/loc.md:16-43, rust-code-analysis-book/src/metrics.md:16-37

Architecture and Data Structures

The Stats Structure

The core data structure for LoC metrics is the loc::Stats struct. It aggregates the results of the different suites (Sloc, Ploc, Cloc, Lloc) and tracks statistical values across code "spaces" (functions, classes, etc.).

This diagram illustrates the composition of the main Stats structure used to store and aggregate LoC metrics.
Sources: src/metrics/loc.rs:177-196, src/metrics/loc.rs:12-87

Metric Calculation Logic

The Loc trait defines a compute method that is implemented for each supported language (e.g., PythonCode, RustCode, JavaCode). The computation relies on the kind of the AST node provided by Tree Sitter.

1. SLOC Calculation: Determined by the difference between the start row and end row of a node. If it is a function space, it includes the signature line.
2. PLOC Calculation: Uses a HashSet to store unique line numbers where instructions exist, ensuring a line is only counted once even if it contains multiple nodes.
3. LLOC Calculation: Incremented when the parser encounters nodes identified as "statements" in that specific language (e.g., ExpressionStatement, IfStatement, ForStatement).
4. CLOC Calculation: Differentiates between comments on independent lines and comments trailing code on the same line to ensure accuracy in the BLANK metric.
5. BLANK Calculation: Derived using the formula: BLANK = SLOC - PLOC - only_comment_lines.

Sources: src/metrics/loc.rs:34-42, src/metrics/loc.rs:309-322, src/metrics/loc.rs:253-256

Implementation Flow

The calculation flow starts during the AST traversal within the metrics function. As the cursor moves through nodes, the language-specific implementation of the Loc trait updates the Stats object.

This flowchart represents the decision logic within the compute function for categorizing code elements into specific LoC metrics.
Sources: src/metrics/loc.rs:324-400, src/spaces.rs:255-275

Language-Specific Variations

The project handles language nuances through match arms in the Loc trait implementation:

• Python: Specifically handles docstrings as comments when they appear as expression statements, but as code when assigned to variables. Sources: src/metrics/loc.rs:360-385
• Java: Includes specific logic for AssertStatement, TryStatement, and ensures that variable declarations in for loops are not double-counted as independent logical lines. Sources: src/metrics/loc.rs:563-587
• Rust: Distinguishes between LineComment and BlockComment, and handles specific markers like OuterDocCommentMarker. Sources: src/metrics/loc.rs:480-505

MI Calculation Dependency

LoC metrics are critical dependencies for the Maintainability Index (MI). The mi::Stats utilizes sloc and cloc percentage to evaluate code maintainability across different formulas (Original, SEI, and Visual Studio).

pub fn mi_original(&self) -> f64 {
    171.0 - 5.2 * (self.halstead_volume).ln() - 0.23 * self.cyclomatic - 16.2 * self.sloc.ln()
}

Sources: src/metrics/mi.rs:54-57, src/metrics/mi.rs:85-94

Summary

The Lines of Code metrics in rust-code-analysis provide a granular view of source file composition. By implementing the Loc trait via language-specific modules, the system accurately tracks physical instructions (PLOC) versus logical statements (LLOC) while maintaining precise counts for comments and blank lines. These metrics serve as the baseline for higher-level quality analysis and reporting within the project.
Sources: src/metrics/loc.rs:219-250, src/output/dump_metrics.rs:188-204