Skip to content

Commit 729afa3

Browse files
committed
Clarify the documentation of some metrics
1 parent 08fb09f commit 729afa3

2 files changed

Lines changed: 49 additions & 6 deletions

File tree

‎src/metrics/halstead.rs‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -171,9 +171,12 @@ impl Stats {
171171
self.u_operands() + self.u_operators()
172172
}
173173

174-
/// Returns the program volume
174+
/// Returns the program volume.
175+
///
176+
/// Unit of measurement: bits
175177
#[inline(always)]
176178
pub fn volume(&self) -> f64 {
179+
// Assumes a uniform binary encoding for the vocabulary is used.
177180
self.length() * self.vocabulary().log2()
178181
}
179182

@@ -195,15 +198,51 @@ impl Stats {
195198
self.difficulty() * self.volume()
196199
}
197200

198-
/// Returns the estimated time required to program
201+
/// Returns the estimated time required to program.
202+
///
203+
/// Unit of measurement: seconds
199204
#[inline(always)]
200205
pub fn time(&self) -> f64 {
206+
// The floating point `18.` aims to describe the processing rate of the
207+
// human brain. It is called Stoud number, S, and its
208+
// unit of measurement is moments/seconds.
209+
// A moment is the time required by the human brain to carry out the
210+
// most elementary decision.
211+
// 5 <= S <= 20. Halstead uses 18.
212+
// The value of S has been empirically developed from psychological
213+
// reasoning, and its recommended value for
214+
// programming applications is 18.
215+
//
216+
// Source: https://www.geeksforgeeks.org/software-engineering-halsteads-software-metrics/
201217
self.effort() / 18.
202218
}
203219

204-
/// Returns the number of delivered bugs
220+
/// Returns the estimated number of delivered bugs.
221+
///
222+
/// This metric represents the average amount of work a programmer can do
223+
/// without introducing an error.
205224
#[inline(always)]
206225
pub fn bugs(&self) -> f64 {
226+
// The floating point `3000.` represents the number of elementary
227+
// mental discriminations.
228+
// A mental discrimination, in psychology, is the ability to perceive
229+
// and respond to differences among stimuli.
230+
//
231+
// The value above is obtained starting from a constant that
232+
// is different for every language and assumes that natural language is
233+
// the language of the brain.
234+
// For programming languages, the English language constant
235+
// has been considered.
236+
//
237+
// After every 3000 mental discriminations a result is produced.
238+
// This result, whether correct or incorrect, is more than likely
239+
// either used as an input for the next operation or is output to the
240+
// environment.
241+
// If incorrect the error should become apparent.
242+
// Thus, an opportunity for error occurs every 3000
243+
// mental discriminations.
244+
//
245+
// Source: https://docs.lib.purdue.edu/cgi/viewcontent.cgi?article=1145&context=cstech
207246
self.effort().powf(2. / 3.) / 3000.
208247
}
209248
}

‎src/metrics/mi.rs‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,15 +49,19 @@ impl fmt::Display for Stats {
4949
impl Stats {
5050
pub(crate) fn merge(&mut self, _other: &Stats) {}
5151

52-
/// Returns the `Mi` metric calculated using the original formula
52+
/// Returns the `Mi` metric calculated using the original formula.
53+
///
54+
/// Its value can be negative.
5355
#[inline(always)]
5456
pub fn mi_original(&self) -> f64 {
5557
// http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm
5658
171.0 - 5.2 * (self.halstead_volume).ln() - 0.23 * self.cyclomatic - 16.2 * self.sloc.ln()
5759
}
5860

5961
/// Returns the `Mi` metric calculated using the derivative formula
60-
/// employed by the Software Engineering Insitute (SEI)
62+
/// employed by the Software Engineering Insitute (SEI).
63+
///
64+
/// Its value can be negative.
6165
#[inline(always)]
6266
pub fn mi_sei(&self) -> f64 {
6367
// http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm
@@ -66,7 +70,7 @@ impl Stats {
6670
}
6771

6872
/// Returns the `Mi` metric calculated using the derivative formula
69-
/// employed by Microsoft Visual Studio
73+
/// employed by Microsoft Visual Studio.
7074
#[inline(always)]
7175
pub fn mi_visual_studio(&self) -> f64 {
7276
// http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm

0 commit comments

Comments
 (0)