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.