Comment Re:Doesn't matter in the end (Score 1) 472
I used to believe (and teach) that comments were a good and necessary thing. Especially "why comments" even bordering on telling the "why" story along side the "how" in the code. The theory was that keeping the two parts of the story together acted as a cross-check during code review and a guide during development and maintenance. That methodology worked really well for a long time, though it did have it's occasional problems. I have now abandoned that methodology and have begun teaching and requiring a fully integrated alternative.
It was a painful transition, but I have been convinced that the best code does a good job at telling both the why and the how. Source code should not be viewed simply as instructions for the computer but rather as an intermediate language that can be shared between the software developers and machines. Both hardware and wetware should be able to interpret the source code with precision and some deeper understanding. It is harder to write that kind of code, but the extra effort has made a profound difference in the quality and maintainability of my code since... Now I teach it the new way.
Here is a blog post I made at the beginning of that transition: http://www.lifeatwarp9.com/2011/02/comments-are-not-literature-i-must-be-mad/
A case in point: I recently had to hand off some of my code to a developer who was completely unfamiliar with the project without much time budgeted for getting them up to speed on it. I was prepared for all the usual breakage and frustration associated with that kind of forced hand-off. Since that code was written with a fully integrated approach in mind the new developer was able to get up to speed quickly and complete their project without any significant learning effort and without any significant errors along the way. Comparing this case with similar cases in the past the "costs" associated with this new methodology are "in the noise" compared to the old.