I agree. I've always been a big believer that documentation doesn't belong in the code, but somewhere else - a doc system or whatever you use to document and comments are meant for understanding the code.

Not surprisingly I use Help Builder for this task. The main reason is not so much of too much comment content in code, but rather the fact that writing comments in code documents usually is a PITA. You have to deal with comment structures so you can't just type and linking in other content is very difficult, so a tool that optimnized to deal with text plus provide you cross linking is for me anyway a better choice. And when you do it this way you end up with something polished that's ready to go.

Now recently I've changed my tune a little with Code Comments in C# which provide at least a standard way to get the text in there as well as basic formatting so that you don't have to worry about text markup for comments. If it's this automated then it does become much easier to write comments into code.

But I'm with you actually. A lot of my help topics have a lot of info in there. Notes, comments, sample code - droppnig all that stuff into source code is a mess esepcially in text files (PRG rather than VCX files)...


Still considering most people don't document at all, I suspect code comments are a lot better than no comments <g>...

+++ Rick ---



>Hi Jay
>
>>We are being required to use this type of function comment header and defect change headers for all methods, function, programs, etc. I really don't have a problem using the change headers, but the function comment header seems incredibly superfluous for predefined methods like the Click event of a checkbox. I could see it being used for user-defined methods, but in the Foxpro predefined ones it just seems to be a waste of time. Maybe it's just the way I see it. Any thoughts on this?
>
>FWIW my view is that the purpose of comments is to explain to other developers who may be looking at the code what is going on and why things have done in a particualr way. I have never seen the value of fancy headers and blocks of code that contain so much information that you can't actually find the code - especially in native methods! Of course, with IntelliSense it is now very easy to construct standard header blocks and insert them with a few keystrokes but my view would still be that if they interefere with the visibility of the code then they are adding little or nothing.
>
>I think it was Drew Speedie who first came up with the idea of adding a "zReadMe" method to all objects where the sort of information that you are showing in the header was encapsulated. The name (zReadMe) ensures it falls to the bottom of the property sheet and doesn't get in the way of the real code. But it does provide a good single place to document the Objectives and Assumptions that the object as a whole relies upon. You can also put the change histroy there so that there is a single place to look for the record of changes instead of trying to hunt through 300 methods every time you want to find a change. Seems like a good compromise to me :)
>
>Just my $0.02