I just came across a blog post from Ian about GhostDoc and Atominerr and had to share my thoughts here about those tools
Figure: Useless but fun!
Generated documentation is useless and not fun. Seriously it is dangerous most of the times.
Let me explain.
I was excited the 1st time I came across GhostDoc as well. I even documented that as a must-have-addin for Visual Studio here http://blog.gfader.com/2008/06/neuinstallation-visual-studio-link-tip.html
But these days I say it has zero value.
Actually worse, it creates pain in the future.
Problems with those tools:
- Once you refactor your method, you have to change the documentation as well –> Violation of DRY
- When you forget to change your documentation you have inconsistencies in your code base –> Hell!!!
Just to be clear:
- I am not against documentation, but documentation that is generated is useless and
- 60% of the time, it causes pain every time. LOL http://www.youtube.com/watch?v=zLq2-uZd5LY
If you document something, document “why” and not “how”. The “how” is in the code.