Archived Weblog Entry - 01/23/2003: "The Dire Need for Source Code Commenting"

Merry Christmas

[Previous entry: "On Basilisk Station and The Honor of the Queen"] [Main Index] [Next entry: "Punch it, Chewie!"]

Links
Topics
Glossary
Archives
Contact
BOTW Scorecard

01/23/2003 Entry: "The Dire Need for Source Code Commenting"
Posted by Maynard @ 05:51 PM MST

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.

Add A New Comment

Name

E-Mail (optional)

Homepage (optional)

Comments

This site is copyright 2001-2004 by Matthew Maynard. All rights reserved. All your trademarks, copyrights, insignia, and other distinguishing characteristics are belong to you. Sharks in suits make for good joke material. Don't leave a mess on your way out.

Links to external websites are valid at the time of article authoring and may decay as time goes by. But we'll always have Paris.

The opinions on this site are those of their author and do not represent anyone else's views. That is, unless and until you agree with them, at which point they become yours as well. Opinions expressed in the comments belong to the comment poster and may be edited for content. Play nice with others, since you want them to play nice with you.