1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
//! # Code Churn and Hotspot Analysis
//!
//! **Code churn** measures how frequently a file or module changes over
//! time — lines added, modified, and deleted across successive commits. On
//! its own, churn is a fairly weak signal: some files change often because
//! they are under active, healthy development, and some rarely change
//! because they are stable, not neglected. The diagnostic power comes from
//! combining churn with complexity: a file that is both frequently changed
//! and highly complex — a **hotspot** — is disproportionately likely to be
//! a source of defects and a drag on team velocity.
//!
//! ## Formula
//!
//! ```text
//! Code churn = lines added + lines modified + lines deleted
//! Hotspot score = churn × complexity
//!
//! churn = change volume for a file over a window (commonly 6-12 months)
//! complexity = a static-complexity measure for the same file (chapter 4.1)
//! ```
//!
//! ## Why it matters
//!
//! Hotspot analysis requires no manual survey: version control history
//! already contains everything needed to compute churn, and combined with
//! static analysis tooling, complexity, for every file automatically. Rank
//! files by the combination — commonly the product of churn and
//! complexity — rather than by either metric alone, since research
//! consistently associates that combination with elevated defect rates and
//! maintenance cost.
//!
//! ## Example
//!
//! The topic doc's government example: a licensing system's hotspot
//! analysis identified a cluster of files representing under 3% of the
//! total codebase that accounted for nearly 40% of all reported system
//! defects over the previous three years — a small, high-churn,
//! high-complexity cluster outranking the rest of the codebase combined.
//!
//! ```rust
//! use software_engineering::code_churn::{code_churn, hotspot_score};
//!
//! // A small cluster with heavy churn (many changed lines)...
//! let cluster_churn = code_churn(220.0, 140.0, 60.0);
//! assert_eq!(cluster_churn, 420.0);
//!
//! // ...and high complexity outranks a large, low-churn, low-complexity
//! // file, exactly the "churn combined with complexity" ranking method.
//! let cluster_score = hotspot_score(cluster_churn, 12.0);
//! let quiet_file_score = hotspot_score(code_churn(30.0, 10.0, 5.0), 3.0);
//! assert!(cluster_score > quiet_file_score);
//! ```
//!
//! ## Pitfalls
//!
//! - **Using churn alone without complexity** — a weak signal on its own
//! that can flag healthy, actively developed code as a false positive.
//! - **Treating a hotspot ranking as an automatic action list** with no
//! human judgement — misses whether the change is essential or accidental
//! complexity.
//! - **Prioritizing refactoring by the loudest complaint** rather than the
//! evidence, which frequently misdirects effort away from where the data
//! shows the problem actually lives.
//! - **Never cross-referencing hotspots against incident or defect data**,
//! missing the validation step that strengthens the case for acting.
//! - **Running the analysis once and never repeating it**, missing whether
//! remediation is actually working over time.
//!
//! ## Sources
//!
//! - Chapter 4.3, Code churn and hotspot analysis.
//! - Tornhill, Adam, *Your Code as a Crime Scene*.
//! - Nagappan, Nachiappan, and Thomas Ball, "Use of Relative Code Churn
//! Measures to Predict System Defect Density," *ICSE* (2005).
//!
//! Topic doc: software-engineering-metrics/locales/en-001/chapters/04-03-code-churn-and-hotspot-analysis.md
/// Code churn: lines added + lines modified + lines deleted over a window.
///
/// Churn on its own is a weak signal — pair it with a complexity measure
/// via [`hotspot_score`] to identify genuine hotspots rather than merely
/// actively developed files.
///
/// # Arguments
///
/// * `lines_added` — lines added across the commits in the window.
/// * `lines_modified` — lines modified across the commits in the window.
/// * `lines_deleted` — lines deleted across the commits in the window.
///
/// # Returns
///
/// The total churn (sum of added, modified, and deleted lines).
///
/// # Examples
///
/// ```rust
/// use software_engineering::code_churn::code_churn;
///
/// // "lines added, modified, and deleted across successive commits."
/// assert_eq!(code_churn(220.0, 140.0, 60.0), 420.0);
/// ```
/// Hotspot score: churn × complexity, the combined ranking signal.
///
/// Rank files by this combination, not by either churn or complexity
/// alone — the underlying research consistently associates the combination
/// with elevated defect rates and maintenance cost. A hotspot ranking is a
/// prioritization signal, not an automatic verdict; investigate top-ranked
/// files with human judgement before acting.
///
/// # Arguments
///
/// * `churn` — a file's code churn over the analysis window (see
/// [`code_churn`]).
/// * `complexity` — a complexity measure for the same file (chapter 4.1).
///
/// # Returns
///
/// The hotspot score (higher indicates a stronger hotspot candidate).
///
/// # Examples
///
/// ```rust
/// use software_engineering::code_churn::hotspot_score;
///
/// // "rank files by the combination, commonly the product of churn and
/// // complexity, rather than by either metric alone."
/// assert_eq!(hotspot_score(420.0, 12.0), 5_040.0);
/// ```