The Dire Need for Source Code Commenting
The Dire Need for Source Code Commenting
I had a bad experience at work today. I was given the assignment of generating help files for our users that covered the new scripting capability in FRED. I found my task very difficult because of one simple thing: I could not understand the code I was documenting. It had no explanation of what the code was intended to do or what it actually did or why it looked like it did. I am partially through the assignment, and I will complete it, but it would be a lot easier if the comments were more clear. This article on Freshmeat.net explains my sentiments exactly. Far too often I have seen code that does not explain itself in plain English. I am tired of it, and I want to encourage any programmer reading this to thoroughly comment their code so that its functionality is clear to even the most inexperienced reader.