Tuesday 17 November 2009

Code comments generators

Writing comments for your code is not the most interesting part of development. I admit that sometimes it's hard to follow company/project guidelines for code comments in a restrictive way, mostly because the lack of time (I know that's a pure excuse).

Some time ago somebody recommended me to use GhostDoc, which would take care of that for me. Tried it today - simple Shift+Ctrl+D combination and your code is fully commented. Some of the generated comments were even quite descriptive. After quick investigation I found out that all the descriptive comments were copied from base classes (e.g. when method overrides the one in the base class, implements interface member etc). For the new members the comments were generated basing on their names.

In my opinion this could be a handy tool if used correctly i.e. only for generating draft versions that would be corrected/extended manually. However, there is a great danger that most of generated comments would be left unchanged (especially if time is limited). Although it would cause all possible StyleCop rules to pass it would still affect the code quality. I will uninstall it right now because I don't want to be tempted when a deadline is close ;) We don't really need comments that don't introduce any new knowledge.

I'm wondering if there are any positive aspects of using them that I didn't think of? Are there any developers who admit that they're using them and can give some examples proving that this can be very useful?

No comments: