Hacker News Reader

Comment by user3939382 | Hacker News Reader

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.

View on HN

> 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.

I 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.

To me the comments section is one thing that sets PHP apart from other languages. Need to learn a new function? Go read about it on php.net, then skim the comments for edge cases.

Need to do something new in Node? Sift through a bunch of search engine spam, read a few dissenting answers on stackoverflow that refer to a previous version, eventually find a library that does what you want, written by skullM4ster2004, plug one's nose and install it.

This 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.

> I will quietly place my face in my hands and weep to the memory of php coding I did 20 years ago.

You should revisit the language. PHP7 was a huge leap forward. It's a different language now.

PHP 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.

When 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'.

I can't attest to how it used to be, but now at least they are in a section labeled "User Contributed Notes". The notes can be voted up or down, so hopefully the dross sinks to the bottom.

I do agree with the sentiment though that these unofficial notes should be taken with a grain of salt. In my experience, they have been more help than hindrance.

Maybe 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.

i 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?

Meanwhile, 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.

If 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.

Clojure crowdsources "examples" (to good effect, IMO). For example: https://clojuredocs.org/clojure.core/assoc-in

The php docs are themselves a public GitHub repo, so it's a bit sad if insightful comments don't affect change in the docs

That’s just it. I have to code with the PHP docs open like some kind of arcane recipe book.

Maybe 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.

It 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.

Does that only cull nulls, or also zeroes, falses and empty strings?

Anything "falsy" -- any item that, when cast to boolean results in false. So, also zeroes, falses and empty strings.

That 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.

Do you really though, or are you being a bit hyperbolic? It's really not that complicated or arbitrary. If you find yourself hitting idiosyncrasies so often you've got the docs open you might just be doing it wrong. There's also some learning to do for any language, no language is so intuitive that you know it without any effort or learning.

All the above said, do enough real work in any language and you'll find cases where the idioms of the language don't map to your work.

PHP isn’t consistent with itself and has abstraction leaks for things that it shouldn’t. PHP does not bring me joy.

Of course I’m speaking succintly above. It’s not that bad, but it’s not that much better either. I’m not going to stockholm myself into using a language just because it’s “mature” if I don’t have to. I may have that relationship with JavaScript but at least in that case resistance is somewhat futile and there are practical benefits to be had.

I don't know any language that this statement isn't true about unless either:

(a) you're a true, deep expert who uses the language all day every day

(b) the docs are so poor it's not even worth having them open

Go might be a contender save for a couple weird features. JS might be with a few ground rules and/or enough tooling.

I’m also willing to grant implicitly that there are tradeoffs here. Languages with small standard libraries usually have big community libraries and vice/versa.

JS isn't directly comparable due to the very delineated nature of ECMA -vs- DOM/NodeJS APIs - ECMA is pretty easy to internalise but you'd be hard pressed to get by without MDN DOM or NodeJS core API docs open (unless as you say you're abstracting them with community libs as you say).

I've only used Go sparingly - I heavily relied on docs, but yeah it may have a shallow learning curve. It's certainly much saner than Python (which seems to be the other language used in my "space" for e.g. ad hoc ops tooling, etc.)

Get a better IDE. Visiting docs for checking return values should be a thing in the past.

My approach (very similar than when I write C or raw JS) is to use a few "cleanup" APIs or libs that hide the nasty stuff (string handling / array iteration / SQL building), because I know I don't want to deal with all the footguns. There were rarely is a performance argument that would need me to do otherwise.

I use PHP daily at work, haven't had to check the docs for quite a while

Exactly. You get it 100%. Come work for me!

just gonna leave this comment here to reply to the person whose blog I've followed years before Browserling was created.

Why, thank you!

Reply on news.ycombinator.com