I’m a beginner btw thanks

We all work our asses off all day doing something we love, and what do we get for it? We get some guy who, just because he has a web site which now a blog, thinking he is better/smarter/whatever and his senseless/brainless sheep followers who bitch because we don’t think like he does.

Just because you do something one way, doesn’t mean it is the ONLY way to do it. GET OVER YOURSELF and do something constructive.

“The top comments were done in javadoc style. It’s more of a habit for me and not strictly necessary because, as you have said, we know from the names what it does, and “n” is pretty obvious as well.”

- Point taken and I can see where you’re coming from.

“There is absolutely NO need to learn all about square root algorithms to fix errors in this code.”

“I have absolutely NO idea what square root algorithms there are out there, nor do I care, nor should I care.”

“I would be a simple user of the library…”

- I completely agree. There’s really no need for us (and I also consider myself an expert since I’ve been in the software development business for 10 years and have built countless, both crappy and exquisite, software solutions for varied companies in many different fields) to learn anything about square roots. I have no time for that either. You shouldn’t care, and I shouldn’t care either. But that dude that ends up maintaining exactly that piece of code we don’t even want to see ever, does care. Comments are not gonna be enough to instruct him on the proper method used in the code, unless you bloat the code with a copy paste from wikipedia between multiline comments. Nevertheless, a search for “approximateSquareRoot” will get the person to this blog and he’ll have all the info he’ll ever need about naming conventions and where to look for square roots explanations. If he searches for “approximate Square Root” he’ll get a webpage with this title “How to calculate a square root without a calculator” (and an explanation to rule over all other explanations on this particular issue); and a wikipedia page that explains the newtons method in a way simple enough to grasp what he needs to do.

“In fact, if I were to come across such a situation, I’d probably just throw the library away and go with something else.”

- So would I…

“I work in the real world. I have a job to do, and I don’t have time to fuck around.”

- So do I. And so does the guy that does need to maintain that code. For you and me, it means using another library. For the other dude, it means either reading this humongous comment on the code (and most programmers are not good at explaining things…. oh the irony), or googling the procedure name and actually finding everything he needs to know in a smaller more organized package.

http://w.holeso.me/2008/08/the-dark-side-of-code-commenting/