As I proposed before, projects with established documentation platforms and teams should be able to opt out of this silliness. I dunno, look at https://stackoverflow.com/documentation/php/194/variables#t=201609142259321734067 , variable variables upvoted? This is madness. There are a billion reasons noone should use those and indeed practically noone does (for example Drupal 8, one of the largest PHP projects out there, together will all the vendor libraries it depends on, has 1 occurence of $$
and that's in Composer install and has hundreds of thousands lines with $
in them). PHP has an excellent documentation anyone can edit and has vetted people curating it. This abomination shouldn't exist.
-
Possible duplicate: meta.stackoverflow.com/q/334291/1079354– MakotoSep 14, 2016 at 23:10
-
You could just not pay attention. Not that hard to do, you don't have to click that link just because it is there. If enough SO users do this then the problem will solve itself. It was already headed that way, too bad that 2K review queue was emptied so quickly.– Hans PassantSep 14, 2016 at 23:10
-
@JonEricson: It might be that they want to exclude things from Documentation which already has very good documentation from it, which I don't see necessarily as a bad thing.– MakotoSep 14, 2016 at 23:11
-
2A fair request - and agreed, that bit is truly awful advice. But can you speak for the PHP team, chx?– PekkaSep 14, 2016 at 23:13
-
I think Peter Cowburn can speak for the PHP documentation team, not me. Should I drag him in here? Is there a point? Is anyone listening?– chxSep 14, 2016 at 23:25
-
2Lots of us listening, @chx; as to what we can do about it, I'm not sure. Plenty of "evil" language features out there for various languages; I don't know that leaving them undocumented solves anything though. Trivia: my highest-ranked question on Stack Overflow by far concerns a mostly-reviled feature of JavaScript... Folks love them some forbidden fruit.– Shog9Sep 14, 2016 at 23:26
-
I'm confused. Isn't Documentation edited by the community? Can't you just put in a proposed change which deletes the example?– Heretic MonkeySep 15, 2016 at 14:13
1 Answer
Near as I can tell, PHP's official documentation for variable variables also suffers from a lack of grave warnings as to their uselessness. Clearly, the problem you've identified is pervasive on The Internet.
Since, as you note, the official docs can be edited, I recommend you edit them and ignore the example here. Ideally, folks will read the official documentation, see your warning about never using variable variables, and purge the concept from their minds... Unable to search for a concept they have no name for, they will then never see the topic here and all will be well with the world.
-
I still see the second part of the original question: If the php docs are editable by anyone should the documentation for php at docs be completely closed and just provide a link "this language has a puplic editable documentation at x, please use this instead"? Otherwise people are tempted to copy the docs over here (because it is missing) instead of updating it there... While this doesn't apply to many topics it looks like it is for php. Sep 15, 2016 at 8:16
-
Kind of a big "if" there, @Simon. Hence my observation that the cautions chx raises aren't in the official docs either. In theory, he could add them... In practice, the current docs describe the uses of the feature, with examples and user-contributed notes.– Shog9Sep 15, 2016 at 16:57
-
Do you think it still is a good idea to duplicate the efforts for a good documentation? And yes: I do think that people may check and better the docs if Stackoverflow asks them to do so (even if they don't get points rewarded for it). Sep 15, 2016 at 18:33
-
php.net predates Stack Overflow by a fair bit, @Simon. I'd argue it's as good as it is because all and sundry have taken time over the years to chip in. If PHP was all there was, it's doubtful we'd have bothered building Docs... Then again, it's doubtful we'd have bothered building Stack Overflow. This question highlights a problem that... I don't think any of us have a ready answer for: how do you document something that is routinely misunderstood and misused in a way that reduces these problems instead of simply providing more material to be ignored or misunderstood?– Shog9Sep 15, 2016 at 21:18
-
The best way to tell people "this is x" (allowing them to understand the code) "but you shouldn't use it because of y [as long as you don't have case z]" is to write it this way. I think the way Brian Tiffin did this for nowadays doubtful COBOL verbs is quite good. See open-cobol.sourceforge.net/faq/index.html#alter (BIG page don't access with a small CPU/internet access) [BTW: he copies those goodies to stackoverflow.com/documentation/cobol and rework them]. Sep 22, 2016 at 10:00