Generated documentation is worse than useless (0 value) and causes pain in the future

I just came across a blog post from Ian about GhostDoc and Atominerr and had to share my thoughts here about those tools

Useless but fun.   Generated documentation is useless but not fun!
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:

If you document something, document “why” and not “how”. The “how” is in the code.

Latest Posts

Popular Posts

 
Google Analytics Alternative