Monday, January 29, 2007 11:10 AM
Willie Roberts
Comments are for weenies
One of my project managers recently recommended that I read a book called Dissecting a C# Application written by the developers of SharpDevelop. They wrote a C# IDE in an attempt to understand how C# works and the source code for the project is available via open source licensing. Apart from a brilliant book they have some brilliant PDF downloads on the website regarding development.
One particular interesting read is a 19 page document regarding code commenting. Well worth the read and probably an eye opener for most developers. My own experience with the importance of comments was highlighted again and I would recommend everyone to take a few minutes and download this document and read it in your coffee break.
The fine Art of Commenting
"Commenting is a royal pain in the posterior" - "Comments are for weenies" - "I can understand my code quite well, thank you very much" - "Good code speaks for itself" - "No time for that, got to get that code out of the door". None of these is a good reason for not commenting source code properly. We will look at these arguments, discuss them and take a look at good commenting practice and its benefits. (Author: Bernhard Spuida)
The document is available here along with a few other worthwhile documents for technical writers and coding standards.
Filed under: C#, SharpDevelop, Comments, Documentation