Quote:Original post by TrueTom
If you are using Doxygen and you want better output, you should give DoxyS a try...
That's nice!
Commenting Style
That's nice!
Quote:Original post by benryvesQuote:Original post by johnhattanAt least in Visual Studio, anything after //TODO: will appear in the "Task List" tab at the bottom of the IDE, even easier to search [smile]Quote:Original post by izhbq412Instead of TODO, I use my initials (JJH). They have the advantage of appearing in no English words, so it's easy to search.
Many of my comments are several lines long, explaining the principle behind the code. I used to write a header of comments above the implementation of every function, but as I got more experienced I discovered that most of the funcions were self-explanatory and no comments were necessary. So now I just put a line of //----------... between the implementations, and the comments, if any, go in the header file.
I also use the // TODO: and // HACKHACK: prefixes.
Writing a brief comment above an unusual piece of code goes without saying.
In the options you can even define JJH as a token that should be shown in the task list... :)
Quote:Original post by Anonymous PosterQuote:Original post by Rob LoachI don't really understand why anyone would want to use a commenting style that is as bloated as XML. Javadoc, Doxygen, Natural Docs etc. generate comments using a much simpler notation which is readable even without passing it through a parser. This seems like a clear advantage to me. Could someone who likes XML comments explain to me: Why?
I use XML In-Code Documentation.
Here's a sample function documented using Doxygen.
int f(){ return 0;}That might be hard to read without a parser. Here's a better version of the function with more meaningfulk Doxygen documentation.
/** * A do-nothing function that just returns zero. */int f(){ return 0;}I admit that would be hard to read without a parser.
The biggest advantage to using this style of commenting is that you can run it through a tool and get nicely-formatted hyperlinked HTML or PDF (or XML) generated. That meay not seem like an advantage of you're tied to a single vendor's costly suite of development tools, but if you're a professional software developer who has been making a living writing portable code for a number of platforms over the decades, past and future, it's a godsend.
I can't explain why someone would prefer to write comments directly in XML, however. That's just mental.
Quote:Original post by Bregma
I admit that would be hard to read without a parser.
I think you misunderstood me. I said that Doxygen uses commenting style which *is* readable without a parser, and even saw this as an advantage (well, duh).
Quote:Original post by Anonymous Poster
I think you misunderstood me. I said that Doxygen uses commenting style which *is* readable without a parser, and even saw this as an advantage (well, duh).
My sincere apologies. I mistook a period for a comma in you sentence.
So you agree the pro-XML camp is squirrelly.
If you're looking for more evidence of mental incopentence, consider those languages (C#, J2EE) which embed directives as XML in comments. What next, adding $JOB and //DATA to your stack of punchcards? Some people shouldn't be let near a design lab. At least not without meds that haven't yet reached their expiry date.
Quote:Original post by Bregma
So you agree the pro-XML camp is squirrelly.
If you're looking for more evidence of mental incopentence, consider those languages (C#, J2EE) which embed directives as XML in comments. What next, adding $JOB and //DATA to your stack of punchcards? Some people shouldn't be let near a design lab. At least not without meds that haven't yet reached their expiry date.
That's the beauty of applying something everywhere. XML is the answer to everything. Actually it isn't. I think that comments should be embedded ASP pages so that the documentation generator can pull them out, execute them on IIS and collect the output. That way I can do just about anything with my documentation since I can use JScript and VBScript to include any sort of thing I might need. (After all I really might need to query some data from some SQL server someplace on the net to generate my docs.) Wouldn't life be wonderful!
I'm glad I'm not the only person who had that reaction to the XML docs. I thought how much extra typing it would be with all those closing tags, how less readable it would become, and how I knew nothing about ASP [grin].
The other doc tools give you straight HTML output and are more readable in the code. The XML thing does have the IDE integration with Visual Studio though.
The other doc tools give you straight HTML output and are more readable in the code. The XML thing does have the IDE integration with Visual Studio though.
Quote:Original post by Boder
Natural Docs have really impressed me.
Check out the Photon Documentation
How did you set up the menu like that? I assume that is your app? :P
As for XML, I took one look and said 'No'. Natural Docs seems fantastic. The only problem is if I create the docs, edit a couple of comments, then rebuild the docs, the new docs don't reflect thos changes. Anyone else have this issue?
Purely visual, but then I guess all comment blocks are.
Before classes I have comment blocks like this:
functions are like this:
notice, I don't use /* */ in cpp files except to comment out blocks of code.
I prefer
//
//
//
//
it's especially a pain when code has a bunch of /* */ comments acting as one line comments. obviously the #if 0 / #endif works fine, but visually /* */ is easier for me to pick out.
Before classes I have comment blocks like this:
/**********************\| class: name || description: ... || ... || ... |\**********************/functions are like this:
//-[Function: name//-[Description: ...// ...//-[Arguments/Return Value: ...notice, I don't use /* */ in cpp files except to comment out blocks of code.
I prefer
//
//
//
//
it's especially a pain when code has a bunch of /* */ comments acting as one line comments. obviously the #if 0 / #endif works fine, but visually /* */ is easier for me to pick out.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement