Developers often take a hard stance when it comes to documenting their code.
Some believe that their code is documentation in and itself because it’s written so well, some believe that you should document every single line, and then there are a few of us that fall somewhere in the middle.
MSDN recently published an article that highlighted four components of good documentation and, generally speaking, I thought it was a good read.
Specifically, the points made are:
- Overview: Explain what advantages developers have in using the platform, and in some cases, provide an architectural description of the platform.
- Getting started: Help the developer get started, in the form of step-by-step tutorials or simpler walkthroughs.
- Sample code: Provide well-commented code samples that developers can build on.
- Reference material: Provide detailed information about each class, member, function or XML element.
You can read the rest of the article on MSDN.
I think these are good points and I’ll be the first to admit that I leave a lot of room for improvement for documenting my code. In college, I was dogmatic about it. I’ve since slacked off.
I’m curious: what’s your take on documentation and do you normally comment your work or leave the rest of us up to figure it out?
Speak your mind...