|
What really irritates me about the C# IDE is the microsoft style insistence. It seems to punish you for not using microsoft style. I use multiline comments and the IDE refuses to copy and paste them correctly with autoformatting on. It can't be difficult, eclipse does it and the code is open source!
Wait, there was a point. Navin has it right with XML comments outside of bodies and regular comments inside bodies. But what is a programmer to do when he (or she) wants multiline comments inside a body without an XML warning? I never could find the documentation but using /**foo*/ inside a method will give a malformed XML error while /*foo*/ won't.
|
|
|
|
|
Sometime I run accross some code that has something like this:
/// <summary></summary>
Serves as code pollution when there is nothing useful written.
Alex Korchemniy
|
|
|
|
|
There are some cases where it's necessary, due to the way VS compiles code comments, e.g., for public enums.
Kevin
|
|
|
|
|
I hate compliler warnings.
But then again I can type so I at least type some lame expletive about .net
|
|
|
|
|
Do people here really use this tag?
I have tried to use it before thinking that I might be able to kill two birds with one stone (comments and sample code showing how to use the component) but I find that writing the code in the comments area is difficult. I usually end up writing it in an adjust project, making sure it works then doing a copy/paste into the example area.
I recently decided that I should just start shipping the source code to the Nunit project (I keep my test in a separate assembly) and tell people that they can refer to that as sample code.
George Carlin wrote:
"Don't sweat the petty things, and don't pet the sweaty things."
Jörgen Sigvardsson wrote:
If the physicists find a universal theory describing the laws of universe, I'm sure the a**hole constant will be an integral part of that theory.
My Blog[^]
|
|
|
|
|
Ray Cassick wrote:
I usually end up writing it in an adjust project, making sure it works then doing a copy/paste into the example area
I do the same. For me it is a symptom of IntelliSense programming - I just can't work properly without it.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
using C# in the 2003 IDE once i told it i wanted an XML comment file it produces a warning for each public item that has no comment.
i am in favour of having comments on functions, since it is quicker to read the comment than the entire function. however i am aware i don't always bother to comment my functions, i say "i will do that later" of course, you know what happens next 
so being nagged about this helps me to insert the comments. i am getting used to the formatting of the XML tags, i don't find it to intrusive. i presume one of these days i will stumble upon the tool that ships with the IDE to turn the comments XML file into readable documentation... in the mean time i run it through ndoc when i remember 
zen is the art of being at one with the two'ness
|
|
|
|
|
feline_dracoform wrote:
i am getting used to the formatting of the XML tags, i don't find it to intrusive. i presume one of these days i will stumble upon the tool that ships with the IDE to turn the comments XML file into readable documentation
It doesn't ship with the IDE, but NDoc[^]is free.
cheers,
Chris Maunder
|
|
|
|
|
When working in a team, XML documentation can save a lot of trouble when distributing the code to another teammember.
Compile the code, generate documentation using nDoc and package the whole thing. Send the package to your colleague and your done. He can continue to use your assembly without having you ask for every method how it works.
The other reason why I use XML documentation is that customers want documentation with their components. Without it, the component is quite useless.
WM.
What about weapons of mass-construction?
|
|
|
|
|
One might also argue that without proper design the component might be useless too. A design document should describe what a component is supposed to do. The comments in the source code should very clearly explain the implementation.
|
|
|
|
|
Yup I agree with that. The whole component should be properly documentated, the design of the component as well as the code usage when implementing the component in another product.
WM.
What about weapons of mass-construction?
|
|
|
|
|
I do full code commenting, including examples in C# and VB.Net. The xml comments are then processed via nant and ndoc to make help files which are then integrated into the VS.Net help files, so we get context sensitive help on our own code.
I have seen a system where the example code is extracted , compiled and run automatically, to verify that the examples were still correct. however this seemed fraught with problems, if I read it right, the examples had to run in the class in chronological order, which my code usually isn't.
Xml Commenting has made a huge difference for me.
Another handy (altho reasonably weak) tool is called documentor which gives a preview of how xml commenting will look like outside of VS.Net, and is a good learning point. It was available from Lutz Roeders site, but seems to have been taken down now.
Being in a minority of one, doesn't make you insane
George Orwell
However, in my case it does
|
|
|
|
|
We used to have some old code tagging system that required gobs of comments like this:
Coding standards at the time also required beginning each comment block with the name of the function it pertained to, so the actual comment block would balloon into something like this:
Note that the comment block already contains the method name three times, and will still be followed by the actual method declaration itself!
Granted, this was a terrible, terrible markup system. And was made all the more useless by the sad fact that maybe two people out of twenty with access to the code actually had the program to extract docs from the in-code markup. But months of wasted time carefully checking the syntax of my comments convinced me that any documentation system that couldn't extract all the information it needed from the code itself was worse than useless. And i stand by that today.
Doxygen is brought up now and again... I've even had requests to doxy up the comments in an article here on CP. I like Doxygen, but i use it for generating a class tree with links into the source files - no special comments.
You must be careful in the forest
Broken glass and rusty nails
If you're to bring back something for us
I have bullets for sale...
|
|
|
|
|
The old AutoDoc (AutoDuck) system was similarly pretty anal about how comments were formatted.
|
|
|
|
|
We have an internal tool that extracts XML tags from comments. We use this to update our change list. The tool runs during each build, extracting the tags from the various sources and then constructing an HTML document that merges all of the tags into a list, sorted by build number.
This lets each developer place entries in his source code that describe qualitatively the changes they're making, and then merge all of the entries into a single list for publishing to the outside world.
Software Zen: delete this;
|
|
|
|
|
Internal classes / members only get xml doc's when its going to be used by others or needs to go into some sort of documentation. Its way too much trouble xml documenting code that no one is ever going to be seen by the greater population.
/bb|[^b]{2}/
|
|
|
|
|
I agree here.
I only use XML comments for the external interfaces. I have a separate way to comment anything internal.
George Carlin wrote:
"Don't sweat the petty things, and don't pet the sweaty things."
Jörgen Sigvardsson wrote:
If the physicists find a universal theory describing the laws of universe, I'm sure the a**hole constant will be an integral part of that theory.
My Blog[^]
|
|
|
|
|
I find Doxygen much better than formatted XML docs (FXMLD), because it works with ALL languages, it does not depend on Visual Studio (try to use FXMLD with device driver projects or eVC++) but is easily integratable. And it's an Open Source Project, too.
I recommend it, and I think Microsoft should adopt it and include in its CD.
Regards,
Andrea
|
|
|
|
|
|
There is some automated document generater in Java as well, it works quite well. What I don't understand is what use is machine-generated documentation. If you want to understand the program, everything you need to know is in the source code.
|
|
|
|
|
I am onboard. Thanks for pointing out Doxygen
|
|
|
|
|
I like the general idea of formatted comments. The reason why I like the MS XML comments is that Visual Studio (and sharpdevelop) does all the formatting for me. I don't care what formatting they use whether it be doxygen or XML as long as I don't have to memorize it.
|
|
|
|
|
XML comments are not unlike JavaDoc which I do use... they are great for generating documentation. It is especially nice to know that if you keep the comments up to date your generated docs will be up to date too (the pragmatic programming concept of not duplicating information.)
That being said, PJ has a legitimate point - it makes the comments hard to read when you are actually working IN the code!
My compromise so far has been, any code that will be part of a public framework or interface gets the special docs, anything else (private methods, in-line commnets, etc.) gets regular, plain-Jane comments.
The generation of random numbers is too important to be left to chance.
|
|
|
|
|
Navin wrote:
It is especially nice to know that if you keep the comments up to date your generated docs will be up to date too
As long as you keep the comments up to date with any code changes 
I wish there was a tool to validate the comments to the code.
George Carlin wrote:
"Don't sweat the petty things, and don't pet the sweaty things."
Jörgen Sigvardsson wrote:
If the physicists find a universal theory describing the laws of universe, I'm sure the a**hole constant will be an integral part of that theory.
My Blog[^]
|
|
|
|
|
That tool you search for is called a brain.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
![Rose | [Rose]](https://www.codeproject.com/script/Forums/Images/rose.gif)