« Site Change | Main | Documentation Progress »

January 06, 2006

Comments

mkamoski

Rabi--

I have a question.

Am I reading you correctly, you are saying that the documentation comments will NOT reside in the actual source code files as standard XML-based comments but rather they will reside in a separate file?

I have never seen it done it that way and I am wondering is there really is a compelling reason to separate the comments from the source code. I see that you say you want to decouple the comments from the code so that the comments can be updated without the source code. With alldue respect, I find this strange and simply had to ask a question.

After all, isn't it the very point of source code documentation to be updated with the source code itself? That is, the 2 should be coupled and update in sync. No?

Anyway, I just thought I would post some thoughts.

Thank you.

--Mark

Rabi Satter

First I am not really talking about source code comments. The documentation is usage information i.e. how do I use a class or method.

The reason to seperate this type information is that it can be modified very rapidly without colliding with development since the documentation might be done by someone other than the developer. While you do have to compile to get the XML file for the assembly it can be done using a skeleton of the class. It also is easier to swap around XML files rather than source code. I know that the XML documentation might be wrong but a malcious person could not do much harm. Ok at worse they can embedded some links but before I added the documentation to my set of documentaion I would check for this. It is much easier to check for this in XML than in actual source code.

So no I am not advocating seperating the source code comments from the code. I am advocating seperating the usage documentation from the code. You are very much right about not wanting to do that with source code comments so the source code is documented.

The comments to this entry are closed.