It generates auto-docs, which are useful. It's just a ridiculously verbose way to do it, and it would be preferable if the documentation could be generated without the repetitive comment.
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
Is this a Word Autosave, or someone aactually hitting save but couldn't be bothered to actually name the doc? It's clearly Word generating the filename.
I think it just goes to show that nobody likes creating documentation.
I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extraction of documentation and intellisense. I am no drone by any means, but this isn't so insane if you give it some thought.
If you are terrible at writing docs, then that’s your fault, not the style guide’s for enforcing documentation. Some fields might be self-explanatory and the docs for them might be pointless, but it’s better to be overzealous here rather than allow people to skip documenting stuff, because then nothing will be documented.
Also, the requirement to have documentation comments is just one rule out of hundreds, so why focus on that one?
I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.
It also adds a lot of drag to iteration to have to go back and rework documentation.
On this kind of project, it's more than syntax-deep. Documentation would have a lot of reasoning and justification in it, which can take deep work to keep up to date.
Even api docstring comments are generally terrible. They aren’t sufficient and the infatuation with automatic documentation in our industry is terrible.
We continually get comments like this, but we rarely get elaboration on why people think this. Please explain what you mean. What's crap about it? We spend a lot of time improving the docs, and without specific feedback we're surprised to hear this.
I really don't want people to start using something like this instead of improving the official documentation. I hate the fact it probably cannot be helped.
To "do the same thing for docs that we did for Q&A"? Yeah, except there just was no sane platform for Q&A before. And for docs there is, you know… the docs!
> Ah - the "repeat the method names with spaces in it" style of documentation.
That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.
I've yet to see anybody that really bothers writing comments or documentation, and, more importantly, keeps it updated to match reality. This is only getting worse these days, where even major libraries and frameworks from Fortune 50 companies barely have autogen'd javadoc-style information available.
It kinda is. Kinda like when documentation is so repeatedly outdated and incorrect, that when you need new information you just skip documentation entirely.
Are you wrong for skipping documentation? Yea, maybe. Is it entirely expected? Yea.
I agree it's a lame excuse not to document code, however there are just some parts that just changes way too often by multiple people where outdated comments can actually lead you astray. The stuff I touch doesn't change often so I'll comment to explain the weird and ambiguous looking parts.
The documentation does _not_ suck. It it literally the most well documented software in existence, a reason for which it has been used for many different things outside its original purpose of text editing.
Yes, it may not be for everyone. But just say that, that it uses certain conventions that are likely outdated for a reasonable set of the population. But you can't say the documentation sucks when you have the below:
I've heard this same quip a lot, and I don't understand it either. I pored through a lot of PHP documentation to write an angry blog post about it, and it was unbelievably painful; documentation for simple extensions was broken into a dozen tiny useless pages, obvious cross-references were missing, similar items are documented in radically different places, etc. There's a lot of text, sure, but it's poorly organized and not all equally useful.
reply