0

The whole point of GhostDocs is obviously to document your code. It asks you to name your methods well to do so. With well named methods however, theoritically shouldn't they be useful enough to be considered documentation?

I just want to hear some pros/cons of current users as I don't want to download it and clutter up my code with unnecessary and duplicating documentation.

SamuelDavis
  • 3,312
  • 3
  • 17
  • 19
  • I've used GhostDocs a lot in the past, but find that I use it less and less these days. My method names are nice and descriptive, and the methods are usually pretty small (5-10 lines). So as you're working with the classes what each method does is pretty easy to understand. However when you're in other classes having the xml documentation is pretty handy - as it is if you use something like Sandcastle to build MSDN style documentation to go with your code. – Simon Martin Aug 14 '12 at 22:08

1 Answers1

2

While self-documenting code helps, if it were all you needed nobody would ever consult MSDN (which is, by the way, an expanded, language-merged HTML form of the XML documentation in the .NET libraries themselves).

XML-doc comments allow you to describe classes, methods, parameters, and other members more verbosely than you'd ever want to do with an identifier. You can recommend best practices, discourage incorrect or "hack-y" uses of your code, detail what could go wrong and why, etc etc. This information is available when your source code isn't (if you compile it properly), and is invaluable when your code isn't quite as self-documenting as you think (many things you might think obvious are because you think a certain way, and not everybody will think the same way).

KeithS
  • 70,210
  • 21
  • 112
  • 164