I have been doing reading lately on documentation and more specifically code comments.  Here are three that you might find interesting.  I'll post more as I find them or they are shown to me.

Are your code Comments a way to say I'm Sorry for the actual Code
1 Common Mistake Involving Code Commenting
Programming *is* much more than "just writing code".

One thing I frequently run into when coding and reading code is the lack of comments in code and documentation for code, especially in the OSS (open source software) community. As a “beginnermediate” developer I often look to quality code for how I should code, but am frequently disappointed when I see little to no comments and documentation. This is especially frustrating when I want to use a new library or technology. From experience and what I would like to see more developers do I want to write more on documenting code.

As I see it there are 4 types of documentation that all code should have accompanying software.

   1. In code comments
   2. Generated documentation from code
   3. Tutorials
   4. Unit Tests

1) In code comments – comments that usually are short descriptive comments to explain 1 to 2 lines of code max

2) Generated documentation from code – In the .NET world this would be XML Comments which when you do a compile against the code you can extract out all of the xml comments for better documentation of what is going on in the code and view them in your browser. Usually XML Comments are descriptive informative comments about large chunks of code

3) Tutorials – One thing that is needed when creating libraries and programs are tutorials on how to use it. Usually well thought-out tutorials are best, but at least something to tell/show the user what and how to use your product is one of the best forms of documentation you can provide.

4) Unit Tests – As a person that works/talks with Test Driven Development people Unit Tests are a great form of documentation because if you use a good naming convention for your tests you can tell what the test is doing. Also it is a form of a tutorial in that you can see HOW to use pieces of code hopefully many different ways.

So, there is a basic overview of documentation types. I will expand on these with full length posts and addendums as time passes.

p.s. Remember just because I write for “newbs” doesn’t mean that experienced developers can learn
something from “newbs” as they often time forget the simple things.

In the Linux world there is a site for newbs to understand some of the technical things in Linux. They call it GrokDoc What this is a site that you can go to for a basic manual on how to do common Linux tasks. The biggest problem with learning Linux is understanding the new terms that are thrown at you. That has been solved by GrokDoc..

Well, what does that have to do with ASP.NET? Glad you asked. Like every good technology a lot of new terms and concepts are introduced which can overwhelm the new user. I know when I started I had no idea what this .NET thing was, and no matter how much I read I never really understood it because of all the .NET specific terms were being used. I was lost. I currently know several people that want to learn ASP.NET, but they are lost because they don’t know how the framework works to even start ASP.NET.

There are plenty of tutorials out there, but they are usually written by experienced competent programmers who know ASP.NET. This results in using hard to understand terms, which easily loses a beginner.

Because of all the problems beginners can run into the ASP.NET community needs a GrokDoc site for ASP.NET. If someone is willing to start it up and administer it I would be happy to write articles. I think as a person that has recently gone, and still going, through a huge learning curve I think I could help.