- Feature Articles
- CodeSOD
- Error'd
-
Forums
-
Other Articles
- Random Article
- Alex's Soapbox
- Announcements
- Best of…
- Best of Email
- Best of the Sidebar
- Bring Your Own Code
- Coded Smorgasbord
- Mandatory Fun Day
- Off Topic
- Representative Line
- News Roundup
- Editor's Soapbox
- Software on the Rocks
- Souvenir Potpourri
- Sponsor Post
- Tales from the Interview
- The Daily WTF: Live
- Virtudyne
Admin
Second post.
Third post.
What happened to the period at the end of the description for DestinationPath?
Admin
That might well be true, but it might be that the XMLDocs process isn't part of the normal build.
Admin
Nothing
Admin
Disable warnings? Warnings are there for a reason, and help producing better code. So one should never disable warnings. Just ignore them.
Admin
That looks like C# to me. Java wouldn't have parameters or results with the type
string; it would always beString. Capitalization matters!It's still horrible.
Admin
Well ..... public class string extends String isn't specified here, but that doesn't mean it doesn't exist!
uh ... YES!
Admin
I'm confused. By default XML doc warnings are disabled and if you enabled them for assemblies they only get thrown for public contracts. Luckily in C# we have internal as a visibility modifier, so it's super easy to have a clean public contract while still have 100% testability thanks to the InternalsVisibleTo attribute.
So if an assembly has an public contract with everything marked as internal that isn't public and the optional warnings for missing XmlDocs is enabled, it should be a breeze to document the few public members.
But personally I never liked XmlDocs to begin with; one sign of clean code is that it speaks for itself, so if you need XmlDocs these days, it's properly just a code base with a tons of unclean code and then those comments are the least problem.
Admin
Nope, I see nothing to get worked up about here. Standard issue sloppy programming.
The thing to remember about the doc tags in C# (yeah it is C#) is that they are just comments and the XML doc generator is an optional step in the build that can interpret those comments. They have no effect on the output binaries so you're not going to get any warnings or errors. After all, you wouldn't expect a warning if you had "// increment i" before an i++;" statement and you deleted the i++, now would you? And what do we all know about comments? Altogether now, "They never get updated."
Now, if you're using later editions of Visual Studio (or it might be a Resharper hint - dunno, after I install R# I just watch out for the hints - it'll warn you if a param hasn't got an entry in the doc block but if you lose a param from the signature it won't warn you that you've got a redundant comment. If you're using VS Code you're pretty much on your own.
Admin
Code rarely speaks for itself.
80% of coding (possibly more) is maintenance code.
Please try your best to help the maintenance coder (ie me). Pretend it's not called something absurd like "XML Docs," which assumes a build of said thing, which almost never happens. Pretend it is a header comment that gives the gist of what the class is for, what the method is for, and what the parameters mean.
Otherwise you end up with what Donald Knuth would describe as "illiterate programming."
Admin
The point of the XMLDocs standard is not to document how the code operates internally. That is, the kind of nfo that would be useful to a maintenance programmer. the intent is to document the use of the code to the devs who consume it. COmpletely different audience with completely different needs.
Agree 1100% that clean code helps maintenance of code. But good XMLDocs documentation helps use of code. And improves the experience of teh various autocomplete "intellisense", etc. gizmos in IDEs.
Admin
It's both.
The purpose of XMLDocs is to define the promise/contract represented by the method. This includes but is not limited to describing what the method does including its input, output, edge cases, exceptions etc. And this is equally useful to the consumer who wants to use it as it is to the maintainer who needs to make sure any changes he makes or fixes he applies do not break that contract.
And in the case that the method just flat out does not work it helps us at least realize what it should be doing so that we can make it do that.
Too often have I seen methods with very non obvious internal behavior and yet no documentation on the grounds that they are for "internal use" which is code for "job security".
Admin
Agree w all your points ref documentation. Ideally XMLDocs would be the contract, the whole contract, and nothing but the contract. And actually truthfully describe the actual behavior too. ;)
As to "job security" over the years I've seen a lot more atrocious code attributable to plain poor workmanship and the crush of management mantras to "do more with less faster today than you did yesterday". Day after day. Pretty soon even the fixes are adding to net technical debt. Deliberately leaving "Only I can fix this" stuff around is more ambitious & foresightful than the usual overworked underskilled memory-limited dev can manage.
Admin
"Pretend it is a header comment that gives the gist of what the class is for, what the method is for, and what the parameters mean."
Comments can sometimes be necessary, but most of the time things should be named so that it's clear what they're doing. And code should be written so that it's clear how it's doing it. The only thing that can never be explained by self-documenting code is why something is being done.
Admin
And would be illegal in Java if it was;
Stringisfinal, i.e., completely closed to extension.Admin
Which is why you document the contract and not the code. The code is the how, the contract is the why.
Admin
Thanks for sharing this! I know how dealing with extra documentation feels like, as I had to cope with lots of it at my nursing school. Understanding the nuances of healthcare concepts in nursing papers can be tricky. Samples https://www.nursingpaper.com/examples/glucose/ break down complex theories into digestible parts, allowing me to grasp and present concepts with confidence.