|
yeah, I know...
My brain just can't help but start to think that this would make a cool add-in
Brains are generally lazy creatures you know. Write once run many and all that...
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:
As long as you keep the comments up to date with any code changes
But that applies reagrdless. Absolutely nothing you can do about that (except have no comments at all).
Kevin
|
|
|
|
|
Ray Cassick wrote:
I wish there was a tool to validate the comments to the code.
At least the Compiler tells you when you have forgotten a new added parameter of a function.
If it would be possible to validate the comments to the code it would be a small step to generate the comments out of the code, so you don't need the comments anymore.....
Greets
Roland
Wenn der Computer wirklich alles kann, dann kann er mich mal kreuzweise.
(Manfred Schmidt)
Follow your Euro notes in their tracks
|
|
|
|
|
Roland Bär wrote:
If it would be possible to validate the comments to the code it would be a small step to generate the comments out of the code, so you don't need the comments anymore.....
And another small step would be to generate the code out of the comments!
I also got the blogging virus..[^]
|
|
|
|
|
Navin wrote:
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.
Having at least a summary comment on public members is useful, as these show up in IntelliSense.
Kevin
|
|
|
|
|
Navin wrote:
it makes the comments hard to read when you are actually working IN the code!
That's why I like code collapsing in IDEs.
|
|
|
|
|
Formatting comments for XML or Doxygen or any other format just makes the comments a lot harder to read in the actual source code files. The comments in the source files should be in plain text for readability, if you want to generate seperate documentation, it should be just that, seperate!
"You're obviously a superstar." - Christian Graus about me - 12 Feb '03
"Obviously ??? You're definitely a superstar!!!" mYkel - 21 Jun '04
Within you lies the power for good - Use it! Honoured as one of The Most Helpful Members of 2004
|
|
|
|
|
I agree, from what I've seen, that Doxygen formatting makes comments hard to read.
I disagree however that XML comments make the comments hard to read. By default if you let VS.NET generate the stubs for you then the summary section will be on it's own line with no formatting at all. Even for those that do share lines, like params, it is a non-event to read the information you require. Granted I come from a web development background but XML syntax makes it very easy to to strip out information by eye.
I don't use XML comments for readability though, I use them because a) they are used in the object browser which is a major plus point for me, and b) because you can easily generate interlinked documentation that gives you high-level and even language specific information about your objects. Neither might be particularly useful if you only work with your own code, but if you have to share code around a team or with third parties it reduces the time taken to learn new objects dramatically.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
David Wulff wrote:
I agree, from what I've seen, that Doxygen formatting makes comments hard to read.
I do find that to be the case if "@" has been used as a delimiter in the comment blocks. We tend to use \ instead (e.g. "\param fred") which seems to make the comments a lot more readable while achieving the same aim.
For example:
void CAddInEventManager::AfterExecute(BSTR bstrGuid, long ID, VARIANT CustomIn, VARIANT CustomOut)
{
.
.
}
Anna
Riverblade Ltd - Software Consultancy Services
Anna's Place | Tears and Laughter
"Be yourself - not what others think you should be"
- Marcia Graesch
"Anna's just a sexy-looking lesbian tart"
- A friend, trying to wind me up. It didn't work.
|
|
|
|
|
PJ Arends wrote:
Formatting comments for XML or Doxygen or any other format just makes the comments a lot harder to read in the actual source code files. The comments in the source files should be in plain text for readability, if you want to generate seperate documentation, it should be just that, seperate!
I felt that way too until I started working with doxygen. After reading the docs for doxygen I realized that it is possible to write readable comments in doxygen format, but that most programmers who use it don't bother to try.. in keeping with most programmers' disinterest in writing comments and readable code in the first place!
|
|
|
|
|
I agree.
As code goes, XML is pretty easy to read. But if i wanted to read code, i wouldn't be wasting time on the comment block at all!
So here's the deal: i'll write XML comments when a version of VS defaults to displaying them with the tags stripped out (or rendered in a visually-pleasing manner). After all, if i wanted to start a browser to read the docs for my own code, i'd write them in a Wiki and skip the XML stuff completely.
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...
|
|
|
|
|
but I also provide everything including fully formatted remarks, examples and exception tags sometimes, especially when I add a Class/Function to our Company Library.
With NDoc you can create really nice Documentation out of the XML Comments.
Greets
Roland
Wenn der Computer wirklich alles kann, dann kann er mich mal kreuzweise.
(Manfred Schmidt)
Follow your Euro notes in their tracks
|
|
|
|
|
I am exactly the same. Most internal stuff will only get the basic level of comments (with references, I am big on those) but anything that is public or that is sufficiently complex to require examples or exceptions will get extra levels added as necessary.
I too use NDoc - I love it!
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
Yes, NDoc does rock...
BUT, I have noticed (just last night) that it is not recognising any summary comments on my Namespaces.
If I add the Namespace summary from within NDoc it is fine but the ones in my code are not being used.
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 is an XML comments shortfall, not an NDoc one - the comments on a namespace aren't carried into the comments.xml file because namespaces themselves aren't represented. NDoc allow you to simulate what you want by having a class named NamespaceDoc in each namespace, and it will use the comments from that for the namespace and ignore the fake class. You can use #if...#endif to exclude the class from non-doc builds.
It's not perfect, but it's an option.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
It's kind of scary that 'comments' can have a shortall. Mostly I thought the source code was supposed to be responsible for that
|
|
|
|
|
The point of XML comments is not to comment your code - you'd just use normal comments were necessary for that - it's to describe it. People reading documentation generated by NDoc, etc, typically don't have the source code available to them to study any more than we have the .NET Framework code when we come to use its classes.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
Ah, that makes sense. Thanks!
It also backs up my assumption that i have absolutely no use for such a thing...
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...
|
|
|
|