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.

1 comment:

Unknown said...

Same experience on my side. IMHO documentation can be a code smell as well. Clean code with expressive class/method/variable names doesn't need documentation at all. Contrary, having clean code and appropriate tests is more documentation you could ever write in some lines of comment.

Normally comments are just needed on smelly code parts, unevitable code hacks or outstandingly complex code another dev might have difficulties to understand.

Post a Comment

Latest Posts

Popular Posts