On Wednesday, 2 October 2013 at 17:48:13 UTC, Tourist wrote:
I don't agree - I often find comments in the PHP documentation
helpful, both for clarifying things and for useful snippets.
We have D.learn for clarification. Comments clarifying the docs
are a bug.
You could say snippets go in comments, but in the first place
people WILL misuse and abuse them for other things. What are you
going to do? Delete the questions? Tell them to go to D.learn?
Heaven forbid you ANSWER it! That just encourages them. And
what if it goes off-topic? Is there ever a "right time" to
discuss array semantics in the std.string.chomp docs? Doesn't
matter; it'll happen.
But even presuming we keep this a utopian column of code spew...
well, take a stroll through stackoverflow. You know what you
find? A lot of commenters who don't have much clue on the quality
of their snippets. Alas, "Thanks, this worked" and up the vote
goes, regardless of whether or not it's incredibly fragile. It's
a "blind leading the blind" scenario.
(http://i.stack.imgur.com/ssRUr.gif)
And again: if it's a solid, clean, idiomatic use case scenario,
it should probably be canonised in the docs. That's one big
advantage TO switching to a page-per-function model: we can do
that and not end up with million-line pages.
As for moderation, disqus has a voting system, and displays
most voted comments on top by default, which is IMO good enough.
Disqus is the worst idea of all because Disqus is external
infrastructure under someone else's control. When -- not "if" --
Disqus dies (goes belly-up, or gets acquired, or otherwise fails
critically at existence), what do you suppose happens to the
people who used it everywhere? Sure, they have an XML export
format. I couldn't find their DTD posted anywhere, so have fun
making heads or tails of it. Presuming you have the time for
exporting. If you don't, well... you're boned, good game, peace
out? Not acceptable. Not even remotely.
Also, a Javascript monstrosity.
Also, voting does not preclude the need for moderation.
-Wyatt
