Automatic documentation generation can be done with a variety of tools, GhostDoc being one of the more prominent. However, by definition, everything it generates is redundant. It takes a look at names of methods, classes, etc. and outputs English that might explain them more verbosely. In the best case, it does what the reader could already do in their head (examples taken from here):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

In the worst, it can actually end up generating bizarre documentation that is actually misleading in its attempt to heuristically figure out the meaning of names:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

It seems that the attitude with GhostDoc is, "it's intrinsically better to have some kind of formal XML documentation", but when that documentation is 100% redundant, why? Isn't it just wasting a ton of space at best?

At my workplace, we have to document everything, and almost always with GhostDoc's auto-generated docs. Do you do this, and are there any rational reasons not to simply leave code undocumented if you aren't going to actually write the documentation yourself?

We're looking for long answers that provide some explanation and context. Don't just give a one-line answer; explain why your answer is right, ideally with citations. Answers that don't include explanations may be removed.

closed as primarily opinion-based by gnat, user40980, Jarrod Roberson, Bart van Ingen Schenau, ratchet freak Sep 14 '14 at 22:15

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 3
    related: Design Document From Code – gnat Sep 8 '14 at 15:23
  • 5
    If you reuse your DLLs, and want to keep the IntelliSense hints about what methods and parameters do, then you need to have comments on every single class, method, and parameter. Otherwise, the project will blow up and the XML won't get created. I'd find using auto-generated comments like that to be a ridiculously lazy approach to doing that. – krillgar Sep 8 '14 at 18:25
  • 10
    It makes reduntant documentation so developers get annoyed by it and fill in correct documentation. Mind games everywhere. – Kroltan Sep 9 '14 at 11:03
  • 2
    sometimes you can give the doc but not the code – Leo Sep 10 '14 at 0:58
  • 2
    Short answer: No. – Thomas Eding Sep 10 '14 at 16:54

12 Answers 12

up vote 13 down vote accepted

[...] document everything, and almost always with GhostDoc's auto-generated docs. Do you do this, and are there any rational reasons not to simply leave code undocumented if you aren't going to actually write the documentation yourself?

No. The documentation generated by GhostDoc is boilerplate (similar to how creating a new OO class in an IDE creates the boileplate for a class with a constructor or something). The usefull part of the documentation is what would follow after adding the boilerplate.

While you have to document everything at your workplace, it seems your coleagues found the perfect way around it: just pretend.

  • -1. Just pretend? That might work great for a one person project that will never be used again. Some level of documentation/commentary is needed even with a one person project if it's complexity is greater than that of "hello world" and if you plan on picking up that project in six months time. In a project involving dozens or even hundreds of people, failure to document/comment can kill the project. – David Hammen Sep 11 '14 at 14:17
  • 12
    @DavidHammen, I am well aware that a project can die due to not enough documentation. Also, the "just pretent" was not an advice to the OP, but a critique of the OP's colleagues. – utnapistim Sep 11 '14 at 14:52

In a statically typed language, Javadoc-style documentation is not for the authors, it's for the consumers. Autogeneration simply makes it easier for the authors to maintain the documentation for other people to consume.

If you're using a statically typed language and are not writing a library for third party consumption, autogeneration doesn't buy you much, and in my experience is rarely used. If you're using a dynamically typed language, javadoc-style documentation is often used to document the types, even for internal use only, but autogeneration doesn't know the types, so all it saves you is avoiding manual copying of the boilerplate.

Either way, don't think of autogeneration as producing a finished product. Think of it as producing the boilerplate for you, so any changes you make manually are significant.

Is there any logical reason to auto-generate code documentation?

From whose perspective?

If I were running the company or the dev group, then there's no good reason. I am staunchly in the "comments should explain why" camp. Forcing people to comment classes/functions/properties is worse than worthless, since they get out of date, they mislead the reader, they're used as an excuse to not make readable code, and so on. These comments waste time both writing them, reading the code, and bugs caused by them. Some will argue that JavaDoc style API docs are a reason to do the commenting, but even under that argument a small portion of your code should be part of the public API, and JavaDoc is not a replacement for actual API docs.

As a developer, I've worked a few places that require comments in these places, despite my opinion. Since I don't have the time or patience to write a bunch of crap that nobody is going to use, I GhostDoc it instead. This allows me to spend that time actually doing stuff that matters. Far more efficient than changing corporate policy.

One other good thing I've found using GhostDoc is that it serves as a check that my names are good. If GhostDoc can't generate decent documentation for a function, it's a smell that my function or parameter names may be poor. While I wouldn't use the tool for just this, it's a nice little side effect if I'm being made to waste my time anyways.

  • 1
    Except that my example shows that GhostDoc can fail to generate decent documentation even when the name isn't really that bad. – Jez Sep 8 '14 at 15:31
  • 10
    Yes, some manager gets to proclaim "we document all of our code" and some other manager thinks everything is great as a result. The uninformed stay that way, but they're still happy. – JeffO Sep 8 '14 at 15:35
  • 3
    @jez - Sure, it's just a smell. Sometimes it's right, sometimes it's not. – Telastyn Sep 8 '14 at 15:52
  • 1
    Answering with a question. Nice ;) – Pierre Arlaud Sep 9 '14 at 7:40
  • @Jez You said the name isn't really that bad. However, the RichTextSelection_Changed method might be easier to use if it belonged to a selection object, and if it weren't named after the type of its parameter. Though as Telastyn said, it just a smell, which could be right or wrong for your design, and my suggestions probably won't improve the GhostDoc output. – dcorking Sep 9 '14 at 13:48

EDIT: I misunderstood the original question; although I think generating documentation (i.e. non-code documents) can be extremely valuable (see original answer regarding Doxygen below), auto-generating comments (which is something that GhostDoc actually does) sounds insane to me. I cannot understand why anyone would expect a program to be able to read un-commented source code and write comments that will genuinely clarify it.

It is conceivable to me that an extremely "smart" comment-generation utility could be programmed to recognize certain patterns and generate "how"-style comments; for instance, it could recognize Knuth's variance-calculating algorithm and provide a comment explaining how it works and why the naive algorithm wouldn't be appropriate. Perhaps such a utility could even be programmed to recognize canonical object-oriented design patterns (e.g. Abstract Factory) and insert comments indicating what pattern is being used and which classes are playing what roles.

But in my opinion, the most useful comments don't explain "how" something works, since the code itself should show this, but "why" comments, explaining "why" a particular thing is being done. As noted by David Hammen in the comments below, in order to generate "why" comments, a utility would need to "read the programmer's mind." Obviously this is impossible.

Based on the given examples, however, it appears that GhostDoc doesn't even accomplish the task of creating true "how"-style comments. So it is, in my opinion, worse than useless, since what it does generate can be inane and misleading (as in the second example).


Original answer: why automatic documentation extraction and formatting is a good idea

My software team uses Doxygen. The primary reason for this is that we need non-source-code (i.e. readable by non-programmers) documentation of code features/behavior/etc, but we feel that it is a better practice to integrate this into the source code itself than to maintain it as a second document. This helps us keep the documentation in sync with the source code (though of course that can't ever be completely ensured, much less automated) and minimizes the overhead of writing documentation (since documentation for a piece of code can be trivially incorporated into the file containing the code itself).

So the focus of our Doxygen use is not to extract information from code itself, but to keep documentation of source code as close as possible to the source code itself.

This also allows us to use one single tool to create both a "theory of operations" that describes our entire codebase and several sets of "release notes" that describe the software product but in fact do not contain any actual "code documentation" in the typical sense.

As for why we would need non-source-code documentation of the behavior of our code, there are two reasons:

  • Our product is not merely software; it's a complex tool that integrates many hardware components, including some fancy lasers and fluidics. We need engineers without much software background to have a good understanding of exactly how the internals of our code behave, and telling them "read the source code" is not going to accomplish this.
  • We must follow quite a few quality regulations, some internally mandated by the company and others legally mandated by the federal government. Although the quality process is (or at least can be) extremely valuable and helpful, it involves a non-negligible amount of overhead, part of which is the duty of the software team to provide this kind of detailed documentation of the software. Again, integrating this documentation with the code itself minimizes overhead and helps us keep the documentation up-to-date.

Note that the second bullet point is pretty similar to the point a couple other answers have made about managers wanting the reassurance (/bragging rights) of knowing that some documentation (regardless of quality) exists for every piece of source code; that way of framing it, however, ignores the fact that externally-mandated documentation can actually have some legitimate advantages.

  • Does Doxygen output English, or does it merely format doc strings that are already written in English? – dcorking Sep 9 '14 at 13:50
  • 3
    @dcorking The latter, although it also tries to organize everything according to the static structure of the code and provide automatic hyperlinks everywhere possible (and these are frequently wrong). – Kyle Strand Sep 9 '14 at 16:40
  • 2
    Actually, it's both. doxygen parses the code and the doxygen comments. Class names, parent class names, data member names, function names, argument types and names, return type: Those all come from the parsed code. What those things mean come from the doxygen comments. Doxygen complains if an item specified as a \param in the doxygen comment isn't an argument, and it can be made to complain about undocumented items. Other than these minimal checks, the problem of comment vs code mismatch is still a possibility. That said, I love doxygen. It's much better than writing an API by hand. – David Hammen Sep 10 '14 at 15:09
  • @DavidHammen so does Doxygen generate sentences, like "Riches the text selection changed."? (I have not used it in many years, and those early versions did not generate English that I recall.) – dcorking Sep 11 '14 at 12:50
  • @dcorking _ I haven't the foggiest idea what you mean by that. Doxygen can't read the programmer's mind. For a good example of what doxygen can do, see this top-level page for Eigen, a rather popular C++ scientific computing package. Poke around! You can see some documentation that's obviously written by humans, other that is purely auto generated, yet other that is a blend of human-written and auto generated. If told to, doxygen will automatically generate fan-in (who references this function) and fan-out (what does this function call). – David Hammen Sep 11 '14 at 14:04

Certainly, automated documentation is particularly helpful when it can reproduce insightful, appropriate descriptions written by the code authors. Otherwise, it's just a glorified automatic formatter.

But formatting isn't useless. There is value in being able to find the public methods of a largish component at one gaze, sorted, and guaranteed to be complete. If you need a frobnick mutator, and it isn't there, you know it isn't there without wading through source code. (Negative results also have value: you know you have to do something, and you have more time to do it because you didn't have to wade.)

So, yes, automatic doc generation adds some value. Certainly not as much as managers probably assume, and usually not even as much as a really good copy editor would, but not nothing.

  • 4
    I don't understand your comment about "wading through source code". Surely in both cases, you would search for something like 'frobnick mutator' or 'frobnickmutator'... how does the auto-generated documentation help? – Jez Sep 8 '14 at 15:14
  • 2
    @Jez Not everyone who needs to know about frobnick mutators is going to be a software dev; they may not understand how to look through source code (which may require familiarity with grep/cscope/ack/etc), and even if they do find the correct file, then they may not find the actual source code easy to read even if it's well-commented from a SW perspective. The ability to look through an index or type into a search bar, then browse through text that looks like it's part of a webpage, can be quite valuable. – Kyle Strand Sep 8 '14 at 18:12
  • 4
    @Jez, A human readable document for non-programmers or at least non-experts is not redundant. Its required. To clearly express what the code is intended to do. It has to be captured before any code is written. And updated as knowledge of the problem(s) and solution(s) grow. The examples quoted aren't worth keeping, but 'its all in the source code' is tossing out the baby with the bathwater. "Auto generation" sounds bad, "no docs, just read the source" is worse. Its like when you ask someone, "What does that do?" and they say, "Hmm, lets run it and find out!" – Bill IV Sep 9 '14 at 10:08

I don't know about other environments but when it comes to large (often open source) PHP projects that other people have written phpXRef is an absolute life saver (especially if the doc is placed online and Google can index it).

Even a badly commented project can at least help me track down where things have been defined and where they are used (for example when refactoring).

When well commented the resultant pages form close to a perfect Bible for the codebase (for my uses anyway).

Furthermore my prefered IDE will auto generate the comment block (if I type /**) which does roughly 75% of the commenting work for me. It is amazing how many stupid things I have been stopped from committing over my coder lifetime just because I have had to explain to other people (and future me) what I am doing. When my comment for the doc generator is bigger than the method this usually means I have not had enough coffee and might want to think a bit harder.

Those self same comment blocks also create the inline completion "help" text so I can see exactly what was expected by the other coders as I am writing the function call. This is a massive productivity boost for me (especially in those rare edge cases where some other helpful developer has written "for goodness sake do/do-not X" which can save a lot of pain.

I cannot stress enough how useful it is to have the expected input types specified in complex (and often badly named) PHP projects and the argument order in less frequently used methods. Even with my own code I cannot always remember what arguments I specified for something I've not touched in an age.

In one instance it meant that the reason for the recurrent problems was that for some reason that reflects badly on prior developers some functions and even constants were defined in a huge number of places (with a degree of inconsistency for added "fun"). That was the sign to walk away from the project.

So reasons include saving later developers a stack of time, keeping track of where functions are called (and defined), spotting silly coding, finding (as another has pointed out) when something is obviously missing, simplifying refactoring (never much fun) and in many cases getting an idea what the developer was trying to do (assuming he or she left some notes).

If the project is complex enough to have multiple licenses going on (no fun) I can quickly see which licenses apply to any given section. Admittedly this is a side bonus.

In larger projects which started before I joined in I can see which developer (assuming they tagged the class file with a name and email) created the class and simply being able to find and talk to the right developer is hugely helpful.

Automatic task lists - using the @todo tag (common in the kind of projects I find myself working in) means that the documentation can keep track of stuff that needs some more work (or features that are acknowledged to be missing). Again my IDE keeps track of this and that alone acts as a good guide as to what needs my attention first.

Also do not underestimate the value of keeping pointy-haired bosses happy at the touch of a button.

Lastly (and very important to me) it removes the non-trivial overhead of writing all that out and then trying to keep it up to date when some (read many) coders commit changes and don't talk to the documentation maintainers.

In short the "auto documentation comments" are vital to my coding habits. I am sure there are many who think that's lame but I am also just as sure that there are a fair few folk that know exactly what I am saying. I don't know how I survived before discovering phpXRef (and my favourite IDE).

In this form it's worse than useless but only because it relies on the public signature alone (which, in the case of Javadoc, is visible anyway to anyone reading the API doc).

But it is possible to write automated documentation tools that consider the body of the method too. As a proof of concept I wrote a lame little Eclipse plugin that adds a list of other methods called from the documented method to the Javadoc. (Not every call of course, you can define filters, by package for example.)

And I've actually found it quite handy when mentally mapping out a completely unfamiliar code base. Granted, it's a very limited use case but it was definitely a help.

Based on that experience the answer to the question is: yes, but we need much smarter tools.

Update: Of course an additional question (one that should be asked before writing any kind of documentation) is who the target audience is. If we're documenting a public API for clients of that API, adding all this implementation detail is a big no-no as anything you put in the Javadoc is technically part of the API.

But if the target audience is other developers working on the same product, automatically adding information on implementation details, such as which methods modify or read a certain field is both acceptable and fairly useful.

It's often good to use documentation generators to create boilerplate or "stand-in" comments that are then later revised by actual developers. I often use Eclipse's auto-JavaDoc function to generate the header comment with parameter types and return values already filled in, then simply add the "meat" of the documentation.

As a C#-developer I use Stylecop, which mandates comments for all classes, methods etc. I autogenerate these comments using a tool. Most of the time, the comments generated by the tool are sufficient and could be inferred by the name of the object, e.g. a Person class has and ID field.

But IF I want to comment a non obvious method further, it is very easy to expand the boilerplate documentation and a few explanations about what it does. As an example: I have a method on my Person class, which returns FirstName + Lastname, but I added a little bit of docu about what's happening when one of both is missing.

In short: I think the boilerplate docu can be detrimental if you never change the text provided by the generator. In that case, it's just line noise. But if you see them as a template, they lower the bar for providing good and useful comments for yourself or your consumers. Could you write the comments without autogenerating them? Sure, but you would have to abide to the format (which in C# case is rather verbose and annoying to generate by hand) and that lowers the chance that you really provide this comment at al..

  • That Stylecop rule can be disabled, though. Rule SA1600 if I'm not mistaken. – Jez Sep 9 '14 at 8:10
  • @Jez Yes, but I decided against it. It leads to a lot of unnecessary comments, but it also encourages me to write the necessary comments. It's not perfect, but what is? What I did disable was the spell checking, which apparently does not even know basic IT words – Christian Sauer Sep 9 '14 at 9:00

Avoid Tautology

The only time you should need any kind of documentation for code is to explain why a method/function is doing something, the name should suffice for what it is doing.

If you are doing something that isn't idiomatic, or violates the principle of least astonishment then documentation is required.

Auto generated documentation that is just a formatter for output of information is almost demanded by consumers of your code. Javadoc does this extremely well.

Not every thing should be documented manually

Things like getXXX/setXXX methods should be self explanatory, so auto-generating documentation that just lets you know they exists will be well received.

Code documentation, at least the "automatic" kind, represents the least common denominator for people trying to understand the application.

The most sophisticated users would not appreciate automatic code documentation. They would much rather have "targetted" documentation that tells them what (little) they need to be told.

The least sophisticated users would not appreciate it for the opposite reason; they wouldn't understand it anyway.

The most "appreciative" users of automatic code documentation are those for whom "a little knowledge" is a dangerous thing." They may or may not understand the documentation (although they are likely to), but they'll feel good about "being kept in the loop." This audience includes most "managerial" types. If that's your main audience, automatic code documentation might be a good thing.

the simple answer to "why generate docs" can be simply answered by showing MSDN.

Imagine trying to write a program that uses any library where there is no API documentation. It'd be a nightmare. MSDN is a great example of the the kind of doc that can be generated from source code and comments and form an essential resource to developers.

If you're writing an application (ie not a library to be consumed by others) then maybe there is a case for not bothered - but even then, how much of a large, internal-only, application doesn't contain bunch of libraries anyway? When you join such a team, having some browsable API doc is going to be helpful.

No tool is going to write your documentation for you, but they do give you the boilerplate that you'd have to write out manually anyway, some tools (like doxygen) will also generate diagrams and reference lists (of called and calling functions for example) that would not be easily discovered even by looking at source code.

Obviously pragmatic common sense should be applied to what gets documented, properties and minor functions can be ignored (and skipped from generation even in the tools), but at no point should anyone say "there's the source code, that's documentation enough" at any time.

protected by gnat Sep 11 '14 at 17:38

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.