I just came across a blog post from Ian about GhostDoc and Atominerr and had to share my thoughts here about those tools. I tried to leave a comment on his blog, but I couldn’t answer the SpamQuiz. LOL #StupidHuman
Figure: Useless but fun!
Generated documentation is useless and not fun
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 0 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