|
Man...I never saw it before...thanks a lot!
|
|
|
|
|
Check out Doc-O-Matic. It'll handle comments in XMLDoc, JavaDoc, C, Delphi and other formats and produces nice looking documentation.
|
|
|
|
|
Seriously, #3 shouldn't be an issue since everyone should be commenting their code! I mean, throwing some one-time use script or app together is one thing, but if you're doing anything that you or others must maintain in the future, comments are a necessity! I know some people subscribe to the "my code is self-describing" idea, or even the "the code should be enough" idea, but how many people - especially in this day and age of "earn more money! get a job in computers!" code monkeys?
As far as code being "self-describing", the only code I've seen do that has variable names 20 characters or more long! Who wants to type that and waste line space for a stupid var?
For the "the code should be could enough" myth, peope like that forget that everyone has their own way of doing things (especially when it comes to coding styles). It may be good enough for you, but someone may be left scratching their head over why you did it that way. Even veteran programmers find it nice to read a comment (as grammatically incorrect as too many developers are these days) than several lines of code. It's easier to get an idea of the code that way. That's especially handy when you're trying to track down a bug in legacy source code.
Where I work, I'm one of the few people who comments code (mostly using the C# documentation syntax, as well as internal documentation). I force my developers to do so, too. The Industrial Engineers, however, (who are entry-level at best) never write comments and are always hacking code in the most inefficient manner, if it's even the right code. The reason (besides sucking)? They can't remember what the methods do or that they already did it!
I used to maintain documentation for our whole suite (it's big!) using NDoc and my own CHM->Help2 conversion program, but it was pointless because they didn't comment their code (the majority of the front-end UI and SQL scripts) and they didn't bother to read it (so instead bugged me incesently about what "X" does instead of RTFD).
There's just no excuse for this. At least add documentation for classes, methods, properties, etc. If not in the C# doc syntax, then in doxygen syntax or whatever you use. Generating documentation from source these days is trivial so there's just no excuse for not doing that.
-----BEGIN GEEK CODE BLOCK-----
Version: 3.21
GCS/G/MU d- s: a- C++++ UL@ P++(+++) L+(--) E--- W+++ N++ o+ K? w++++ O- M(+) V? PS-- PE Y++ PGP++ t++@ 5 X+++ R+@ tv+ b(-)>b++ DI++++ D+ G e++>+++ h---* r+++ y+++
-----END GEEK CODE BLOCK-----
|
|
|
|
|
I agree fully. I try to document my code as well as possible, and I think there will be people (including myself!!  ) who will be very glad that I did. Will even I remember 5 years down the road why I did something a certain way?
|
|
|
|
|
Heath Stewart wrote:
since everyone should be commenting their code!
Stop trolling!
"Vierteile den, der sie Hure schimpft mit einem türkischen Säbel."
sighist | Agile Programming | doxygen
|
|
|
|
|
C........
<edit>
I don't mean C language !
I'm programming in C# and i voted for first option. IMHO xml comments rocks !
</edit>
|
|
|
|
|
 Never thought about 'upgrading' to modern languages?
Rakesh
|
|
|
|
|
I didn't mean C language (I'm programming in C#  )
I mean CLi......:rolleyes:
|
|
|
|
|
New style for documentation level . Old style for 'hints for the handyman' for anone reading my code.
|
|
|
|
|
I tried the XML - Style first, but that's to much of a pain to type.
"Vierteile den, der sie Hure schimpft mit einem türkischen Säbel."
sighist | Agile Programming | doxygen
|
|
|
|
|
One extra slash is too much effort? 
regards,
Paul Watson
Bluegrass
South Africa
Miszou wrote:
I have read the entire internet. on how boring his day was.
Crikey! ain't life grand?
|
|
|
|
|
|
But VS.NET types it all in for you!
I find it second nature being a HTML lamer.
regards,
Paul Watson
Bluegrass
South Africa
Miszou wrote:
I have read the entire internet. on how boring his day was.
Crikey! ain't life grand?
|
|
|
|
|
Yeah, but it conflicts with my typing style, and for me it reads like YUCK.
Further, I know how to get what I want with doxygen - XML comments are comparedly inflexible for me.
"Vierteile den, der sie Hure schimpft mit einem türkischen Säbel."
sighist | Agile Programming | doxygen
|
|
|
|
|
The best thing about using the /// XML style comments is the hints you get through IntelliSense afterwards. It's great when you have a method with 8 overloads and a large range of parameters for each one.
I always try to get a good /// in there for every public method, property etc. But I also use // wherever a comment is needed throughout the code.
|
|
|
|
|
And don't forget those // TODO: blah, // HACK: blah that both serve as inline documentation, and handily appear in the Task pane, too.
Doxygen was great, but we dropped it like a stone when VS.NET came along - we just have to type fewer characters, and get more flexibility in terms of formatting, inclusions etc.
I have to admit, however, that I might be tempted to use Doxygen still, if I *wasn't* using VS.NET, as it is more compact if you don't have intellisense behind you.
Matthew Adams
Development Manager
Digital Healthcare Ltd
|
|
|
|
|
At least he is commenting code!  Almost 13% is way too much for #3. 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.21
GCS/G/MU d- s: a- C++++ UL@ P++(+++) L+(--) E--- W+++ N++ o+ K? w++++ O- M(+) V? PS-- PE Y++ PGP++ t++@ 5 X+++ R+@ tv+ b(-)>b++ DI++++ D+ G e++>+++ h---* r+++ y+++
-----END GEEK CODE BLOCK-----
|
|
|
|
|
XML documentation is great when using VSNET, since it adds all those tags automatically. It also comes very handy when during intellisense and quickinfo for your own classes.
But in case u r out with sdk coding...oh that would be too much typing...
Rakesh
|
|
|
|
|
Yeah I hate the new comment style... it is very un-reader-friendly when reading source... and that is what we spend most of our time doing, no?
I spent 2 years writing Java and using Javadoc format... and I thought that javadoc was uncool because it was a domain-specific format...
But now I see the irony that MS has chosen an "industry standard" format (XML) and I hate it and long for the days of javadocs or doxygen again!
|
|
|
|
|
I have mixed feelings about the /// xml style. I love how it makes documentation easy, but as many others have said, it makes reading the source code tough.
I wish VS.NET had an easy way to toggle whether the comments were visible or not. (If someone has a way or a good macro that does the trick, I'd love to hear!)
<insert incredibly="" witty="" sig="" here...="">
|
|
|
|
|
I just love the /// xml comments, since I don't have to look at the source code to find out what the functions does a couple weeks down the road.
I have really bad memory 
|
|
|
|
|
I think it is great having the /// comments. I generate good documentation, and the code and ddocumentation source comes from the same location. I use a similar method in my XSLT's, and a similar, but much cruder method in my javascripts
Being in a minority of one, doesn't make you insane
(George Orwell , I think)
|
|
|
|
|
|
My programming assignments have to be commented heavily so I usually use the old school method, although its python not C/C++ so it is more like # blah blah blah
Matt Newman
Sonork: 100:11179
"If you're Noah and you're facing the Flood, don't call a lawyer, start building an Ark." - David Cunningham
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
