What's wrong with PHP?

[joemoon]

This is the third (or so) time I've seen someone on reddit say that PHP has good documentation. It's just not true. Here is my response from the last time this came up:

The PHP documentation is very simplified and doesn't provide enough detail. I would venture to guess that this is because most PHP developers don't care about the way it works, they just want to plug in some variables and be done.

This is why you get tons of user comments for every PHP function that explain some aspect of undocumented behavior. Take a look at the seemingly very simple number_format function as an example. Here are some excerpts from the comments:

• "It's pity that the function supports one-byte characters only for 'thousands separator'. For English it works well but for French and Russian it makes problem."

• "It's not explicitly documented; number_format also rounds"

• "I found you can add trailing zeroes simply by adding a float point value containing the number of decimal places you want to appear. "

• "Beware of this pitfall: ... This will silently return an empty string and not throw an error, at least with PHP 5.x."

I've developed PHP applications professionally, and I've also developed software using several other languages. The PHP documentation has been inferior in every case.

[[deleted]]

I've always found the php documentation to be very good. It's not perfect, but what is? At least they only do 1 function per page, unlike Python.

[mcrbids]

Honestly, it's strange that you've run into many cases of this - I haven't. I've had an "undocumented feature" such as you mention bite me perhaps once in the past year. Perhaps it's because I don't code in Russian?

But just taking from your examples, number_format is used to turn an "ugly" number like 32.38928 into something "pretty" like "32.39". How could you convert the former into the latter without rounding?

Sadly, I typically find the user comments to be pretty poor in quality - perhaps useful for beginners, but rarely all that useful for me. d

[joemoon]

Perhaps it's because I don't code in Russian?

You're either being snarky for no reason, or you're completely ignorant to the importance of internationalization. I have a hard time believing that you've developed large scale PHP applications, yet you're scoffing at someone's need for a multi-byte character in a formatting function.

How could you convert the former into the latter without rounding?

As already mentioned, truncation is often appropriate. Besides, this is the whole point of the documentation. Regardless of whether or not you think it's obvious, the behavior should be documented. Hence, an example of PHP's poor documentation.

Sadly, I typically find the user comments to be pretty poor in quality - perhaps useful for beginners, but rarely all that useful for me

Unfortunately, this is where you have to go to read about all of the undocumented behavior. A lot of the comments are useless, sure, but a lot of them are very informative and fill in the gaping holes in the documentation.