Documentation Maintenance

Question

I'm looking for some kind of tool or technique to help me keep track of the functions and methods in my code that may be required to re-evaluate the documentation. For example, let's say I have the following method:

/// <summary> /// Returns the 1-based index value of the supplied value in this data structure /// </summary> public int GetIndex(string value) { // returns 1-based index } 

Then, in a furious coding session, I make changes to my GetIndex () method and change it to return an index based on 0, but not update the title of the documentation:

 /// <summary> /// Returns the 1-based index value of the supplied value in this data structure /// </summary> public int GetIndex(string value) { // **returns "0-based" index** } 

Is there anything that can mark a method or function as modified to reevaluate the documentation? This would be mainly for my personal benefit for coding, but I could also see that it was configured based on the command code, perhaps for those responsible for maintaining the documentation. (Target value for .NET, but search for any possible methods)

Any thoughts? Thanks!

Edit

One answer to this question indicated the identification of changes using version control. Anyone have thoughts on how this can be used to solve a problem?

Answer 1

Now that I get the gist of the question (and I assume that there is an audience for the documentation :)), my thoughts would be what you need:

• Some server processes that download each version of svn and run your service code on it. (continuous integration server such as cruisecontrol.net).

• In this server process, you need a program that can parse C # enough to read xml comments for each function, as well as extract code for that particular function. It will compare and update the current value:

• A database containing comment text, in combination with the code of the function to which they are applied. (or, alternatively, some hash value of both).

You can accept the rule that if a function comment is registered as updated, it will be invalidated if the code for the next version differs from what was seen last time.

If, on the other hand, the comment is known to be out of date and it has changed, your server should note this. This can be interpreted as the fact that the comment is now considered OK (as it is revised). But there should also be a way to manually force the function to be considered relevant (without the need for a fictitious comment change). You will need to write an interface for this, and in this user interface you will want to see the comment text and functions (and maybe even something like a change log.

Answer 2

I do not think this is achievable or desirable. I will try to explain why.

I don’t think it’s possible, because you have to analyze both the comment (in natural language) and the code, and decide whether they describe the same behavior. Deriving code from static code analysis is much more complicated than you think (google for "stopping problem"). Natural language is even more complicated.

I do not think this is desirable, because if a comment can be “calculated” by checking the code, it will be redundant and, therefore, a violation of the principle of DRY (Do not Repeat Yourself). In this case, there should be no comments. This saves time (no need to write), clutter (it doesn't distract you from the code), and it also can't be wrong / misleading anymore.

Of course, there are exceptions when commenting code is required (for example, when you provide an API for a command elsewhere). But also in this situation, you better explain the non-obvious aspects of your code. In your example, I would warn about indexes based on 1, but I would not explain that the index is 0, since I consider this to be the default.