4 ms·
I’ve been using PHP since 2003 and it’s my full time job and this doesn’t ring true. Very, very rarely is a gotcha not in the docs comment section.
by user3939382 4y ago
I’ve been using PHP since 2003 and it’s my full time job and this doesn’t ring true. Very, very rarely is a gotcha not in the docs comment section.
- pkrumins 4y agoExactly. You get it 100%. Come work for me!
- __del__ 4y agoi always found those comment sections to be so odd — fifteen year old comments about a common pitfall and the information never makes it up to the official documentation? i suppose it's fitting for a web-centric language to crowd source its docs on a website, but does any other mainstream language do this?
- mxschumacher 4y agoThe php docs are themselves a public GitHub repo, so it's a bit sad if insightful comments don't affect change in the docs
- oneeyedpigeon 4y agoMeanwhile, I find the PHP docs far more readable/accessible than almost any other language. Compared with the official Python or (shudder) Java docs, and they're far superior, IMO.
- cnity 4y agoClojure crowdsources "examples" (to good effect, IMO). For example: https://clojuredocs.org/clojure.core/assoc-in https://clojuredocs.org/clojure.core/assoc-in
- saurik 4y agoIf it makes you feel any better, at least the comments are next to the documentation? Really big projects that people rely on every day -- things like Rust's Cargo or Google's Flutter -- are riddled with bugs and limitations, requiring frustrating boilerplate workarounds to make basic things work correctly, and they generally only have mention of the problems in the comments on the billion 5-10 year old open issues in their task tracker.
- CSSer 4y agoThat’s just it. I have to code with the PHP docs open like some kind of arcane recipe book.
- bearmode 4y agoI use PHP daily at work, haven't had to check the docs for quite a while
- user3939382 4y agoMaybe it’s the frequency that you use the language? I go maybe 5-10k loc between needing to lookup anything in the docs at all, and 5-10x that where the issue I need guidance on isn’t in the formal doc. Much more frequently I’m looking up something related to the tools and libraries I’m using. The only surprising thing I’ve learned about PHP at the language level in the last 6-10 months is that you can call array_filter() without a callback to cull nulls.
- sjamaan 4y agoDoes that only cull nulls, or also zeroes, falses and empty strings?
- sergiosgc 4y agoAnything "falsy" -- any item that, when cast to boolean results in false. So, also zeroes, falses and empty strings.
- sjamaan 4y agoThat was my point - OP said it "culls nulls", and the pitfall is that kind of thinking - if you think of it as removing nulls and you're not mindful, you might be deleting things from the list you don't want to be deleting.
- CSSer 4y agoIt could be, but I also never felt like I really got to the point you're talking about in 2 years or so of moderate usage. I've been productive in it, and it's not like I'm hung up on control flow or something. I don't hate the language either. I still have to use it from time to time, but it just doesn't seem like it makes sense for a lot of green field work due to this. It's mostly things like parameter order for certain built-ins that aren't intuitive and/or finding built-ins I've never used or heard of because there are so many obscure ones (there are nearly six thousand) that keep me coming back. For example, how do you disable errors in a DOMDocument? It ought to be as easy as DOMDocument->setAttribute("errors", "false"), but no it's a separate function call to libxml_use_internal_errors(true). There are like five other similar function calls for this too. PHP has abstraction leaks and little inconsistencies like this everywhere. Granted, languages with small standard libraries, like JavaScript, by contrast get an easy cop out to blame the community of various package maintainers here. But at least in that case someone can always just write a better library.
- jasonm23 4y ago> in the docs comment section. A classic boiled frog statement. __It's not undocumented, someone posted a comment about that bug...__ I will quietly place my face in my hands and weep to the memory of php coding I did 20 years ago. Seems the same nonsensical masochism is still going strong.
- ehnto 4y agoThis is a very common trope, someone who hasn't touched PHP in decades who still thinks they know anything about the language and ecosystem now.
- bearmode 4y agoPHP has changed a lot. You should give it a try and stop thinking of it as the same language with the same flaws it had two decades ago.
- saurik 4y agoI mean, I am by no means an expert in PHP, and in fact most of my knowledge of it comes from hating on it (or having been thrust into the unfortunate position of being the system administrator for a popular MediaWiki instance), but even in my limited experience with it from a couple lifetimes ago I know that most of the documentation for PHP is crowdsourced in the documentation comments section. That might be depressing, but that isn't what that comment was defending: it does feel likely to be true that there aren't many "unknown unknowns" waiting for you in PHP.
- daef 4y agoWhen I had to code in php I've written a css-rule for my browser to hide the user contributions to the docs, since they where often misleading if not plainly wrong. I remember no discernible border between 'official docs stop here' and 'user contributed opinions start here'.
- artificialLimbs 4y agoMaybe that's how it was, but it has a clearly defined header that says "User Contributed Notes" now, with up/down vote counts on each comment.