Some weeks ago my son who works for one of the iconic software companies rang up and asked, "What is the definition of Standard Deviation?"
I was rather taken aback. He has a good degree in Mathematics and his college days are not all that long ago - at least compared to mine. So was it a trick question? Since at the moment I was having lunch, I used that as an excuse to get back later with the answer.
When I did get back with the definition (without having had to google it :-), I got the full story.
He was going through some code where the comments described a wrong computation for Standard Deviation. Yet, given the halo around the people who generated the code he doubted his own understanding. As it turned out the code was correct. The comments were wrong.
Imagine if a maintainer decided to change the code in accordance with the comment.
Here are the mistakes made by the author of the comments:
Describe the WHAT. In this case it is sufficient to say, "The following computes the Standard deviation of ....". If required a reference to a standard text or a Wikipedia link can be provided.
Describe the WHY? What use is going to be made of the Standard Deviation? Why is it required to be computed?
The HOW should be in the form of an algorithm. Again, in many cases the algorithm would be available in standard texts, or in Wikipedia; provide a link.
And use Intentional Naming. Use StdDev, or Sigma; not S.
