For better or for worse I've decided to join the revenue assurance project and dig into C#. I'm at the tail end of online lesson 2 (of 5). The online lessons aren't bad, actually.
Well, anyway, here are my initial impressions:
I'm about as skeptical about this one as I was two years ago when it was first announced.The ability to use/// for inline XML documentation is nifty.
Consider XML as a reasonable default syntax, much like the GPL is a reasonable default license (if you intend all users of your software to be on an even playing field). That's default, not universal. Over the years, I've found that the mindset when I'm writing a document (in XML, LaTeX, Pod, HTML, whatever), is different than the mindset when I'm programming.
There's a benefit to using structured documentation conventions within code. But most comments aren't structured (and shouldn't be, or else they'd be documentation, not comments). The best solution I've seen is something like Pod, where the structure is expressly intuited (there are always some improvements that could be made, of course). Also, Pod works quite well as a documentation format that works when intermingled with the code, preceding or following the code (especially after __END__).
Re:XML Comments
koschei on 2002-05-09T17:54:24
I think a more universal literate programming system is needed.
All the existing ones tend to have some problem with some aspect (typically they're too tied to a particular language for either the doco part of the code part).