Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

When I write comments for auto generated documentation it can become irrelevant after a few changes of the method. Do we have any system to automatically check, prevent such situation and warn developer to update comment? Maybe some VCS hooks?

share|improve this question

closed as not a real question by Jim G., Walter, Glenn Nelson, MichaelT, gnat Feb 17 '13 at 19:55

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

3  
How would such an application measure "relevance"? –  Jim G. Feb 17 '13 at 18:23
    
Application of course can't measure relevance, but developer can. I'm asking about system which can detect that method was changed enough since last change to warn developer to check comment and rewrite if needed. It can be useful when we maintaining documentation for company knowledge base and need to guarantee that info are actual. Maybe I do not know this area good enough and I trying to find stupid solutions. –  zakhej Feb 17 '13 at 18:57
    
Yes such a "system" exists. It's called a "code review". –  user16764 Feb 18 '13 at 0:17
add comment

1 Answer

up vote 2 down vote accepted

"If the code and the comments disagree, then both are probably wrong." — Norm Schryer.

The best you can do is to automatically generate as much documentation as possible from the source itself.

For example, if you have code to implement a state machine, and your documentation should include a state diagram, write a program to determine the states and transitions from the code, feed to to, e.g., graphviz, and output a diagram to be included in your documentation.

If your documentation should include the calling signature of a method, extract as much of that as possible from the actual source.

If your documentation should have examples, have a system that tests the examples, and then includes relevant extracts of the tested examples in the documentation.

And so on.

But otherwise, the rest of the documentation is up to the people to maintain. And that means that procedures, not automation, are going to be the key to keeping those up-to-date.

share|improve this answer
    
+1 for generating documentation from source. When done this way, code reviews can help catch documentation sections that must be updated as the routines change. –  Sparky Feb 17 '13 at 18:50
add comment

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