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

Question

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?

Answer 1

[...] 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.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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.

Answer 6

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.

Answer 7

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 source of 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.

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.

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.

So, the 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)
• (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.
• Getting an idea of who to talk to about a project file.
• Automatic task lists

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

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 folks that know exactly what I am saying. I don't know how I survived before discovering phpXRef (and my favourite IDE).

Answer 8

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.

Answer 9

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..

Answer 10

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.

Answer 11

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.

Answer 12

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.