@@ -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}
0 commit comments