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.
1 comment:
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