9 ms·
"5. Arguably the best documentation for any language" I should very much like to see that argument. My impression of PHP documentation (after using it for thr
by hapless 16y ago
"5. Arguably the best documentation for any language"
I should very much like to see that argument.
My impression of PHP documentation (after using it for three of the last five years) is that it's a endless pile of bullshit whose primary content is in user comments on the doc pages.
That's the core library. Third party libraries are typically wholly uncommented and undocumented.
- georgieporgie 16y agoWhile I think you're being a bit harsh, I think you raise a good point. Admittedly, I haven't done significant PHP development since PHP4, but my recollection of the documentation was that it was mediocre, and that all of the really good information was in the community comments.
- jamesgeck0 16y agoAlong with a some _really bad_ information in the community comments. The most blatantly horrific advice gets rejected or removed, but it's still best to search around to verify that the methods advocated are the best ways to do things.
- andjones 16y agoThe accessibility of PHP is its strength and downfall. There exist so many third party libraries because of the low barrier to entry. But as more people join the party, the party moves toward the average. The average third party library is an untested and undocumented mess. I do not think this is specific to PHP.
- warfangle 16y agoEspecially when it comes to wordpress plugin land. I've done a few freelance projects in wordpress-land, and for what would seemingly be normal additions in functionality there certainly existed "five-star" plugins that almost got you to where you needed to be. Except they did everything in a non-ACID database table (or wholly non-wordpress-oriented). Or they weren't extensible at all. Or they were unmaintained piles of crap. Usually I ended up throwing my hands up in desperation and writing my own, customer-specific plugin that would get the job done. If the average PHP library is untested and undocumented, they're a couple steps ahead of the average Wordpress library. (also, I might say, the Wordpress documentation is horrific. Hell, the entire structure of that project is horrific to work within. It's built to be easy for noobs ["the loop"], but makes it difficult to keep anything organized or nicely packaged)
- 6ren 16y agoSounds like disruption: lower quality on the metrics that mainstream programmers care about; and targeting non-consumption (i.e. making programming accessible to people who wouldn't otherwise be able to). People who don't have access to anything are delighted to have something. Therefore, PHP gets a foothold even though it's lower quality. This is the beginning of disruption. The next part of disruption is improvement. And PHP is improving. At the same time, other programming systems are improving - C#, python, ruby, objective-C even Java has improved (generics etc). So it might seem that PHP will never catch up - which is probably true. But the crucial disruptive insight is that it mightn't need to: programmers might not all need all the extra improvements in mainstream languages, for all tasks. One piece of evidence is that PHP itself is already good enough for some tasks. For any advanced functionality, it's often possible to think of use-cases that wouldn't benefit from it. This means that it's possible for mainstream languages to "overshoot" what most programmers require for most tasks (to "overserve" them, like serving more food to someone who's already full). But, you might say, mainstream users are increasing in their ability to use advanced functionality as they learn more, so they can use the extra functionality (the patrons' stomachs are getting bigger). The interesting possibility is that the rate of improvement of mainstream languages may be faster than the rate of increase in the ability of programmers to use it (the servings getting bigger faster than the patron's stomachs are) - disruptive research has found that this is usually the case. It's because companies developing competitive products work really hard at improving them (to remain competitive); but consumers don't like to change their behaviour that fast. The final stage of disruption is that programmers leave their mainstream language, and switch to PHP because although it's not as good, it's good enough for their task, and it has other benefits (not sure what they are for PHP, but for disruption it's usually: cheaper, more convenient, simpler - the latter two are true of PHP, but as it adds functionality, it would seem it must lose them. It will just copy mainstream languages). But I can't imagine this happening, so therefore either disruption doesn't apply in this case (perhaps because a company isn't running PHP? Or because programmers themselves are unusually competitive and early-adopting, and even if some don't want to change their behaviour that quickly, there's another generation coming up real fast? Or as I said above, PHP can't retain its simplicity of being a template language while adding advanced features) - or my imagination is lacking.
- akavlie 16y agoAgreed, I find it's often very sparse myself. Compare to the Python standard library docs, which tend to be much more thorough.
- larrik 16y agoI think the Python standard library docs could be a bit better. There is rarely example code, and they can be a bit hard to follow if you are trying to figure out what the library even does. Personally, I'd like to see them start with example code, and then highlight a few of the more important functions, and THEN get into the gritty details. As it is, I'm about as productive just dir()ing everything in the interactive shell, and then seeing what happens (sometimes falls down with passing options, though), and that's almost as good as the docs. PHP though? Yuck. Although it's tons better than Joomla's documentation.
- MichaelSalib 16y agoPython's stdlib docs could improve in places (I'm looking at you lib2to3), but a lot of the modules do include examples (see http://docs.python.org/library/collections.html#module-collections http://docs.python.org/library/collections.html#module-colle... for an, um, example). My sense is that you see heavy examples in newer modules rather than older modules because of the rise of doc string tests. But the real reason I wanted to comment: stop dir()ing through modules! Install ipython and learn to use ? and ??. Life will be so much easier.
- larrik 16y agoI've been using DreamPie recently, but I'll check out IPython. Thanks! Edit: Checking it out now (actually already had it installed, thanks Ubuntu!), the ? and ?? things are just awesome.
- jamesgeck0 16y agoThe docbook source for the core library is actually available in a sort of online wiki editor thing, so in theory anyone can improve it. Unfortunately, I've forgotten the URL and I can't find it via Google.
- config_yml 16y ago>> My impression of PHP documentation (after using it for three of the last five years) is that it's a endless pile of bullshit whose primary content is in user comments on the doc pages. Agreed, but the user comments include a huge collection of common problems and their (mostly) quick n dirty solutions. This is a part of what's making the language so accessible for newcomers. Of course it doesn't necessarily encourage best practices.
- damncabbage 16y agoThe worst part is that, though some comments are useful (and point out holes and inconsistencies in the "real" documentation above), a lot of the time a large chunk of the comments are misleading or flat out /wrong/.
- ch0wn 16y agoI came to say that. Even without comparison it should be very obvious that the PHP documentation is incomplete and badly written. The user comments can't make up for that, especially since there is no quality control for them. The python documentation is an example of good documentation. And again, it's tied to the language's culture, where documentation has a really high priority.
- pavel_lishin 16y agoI don't know, I think the user comments add a great deal of valuable information - specifically, they're great examples of what you shouldn't do.
- eru 16y agoYes, and even the Python documentation has lots of holes in them. I'd often like a stronger emphasis on the types of arguments and what gets returned.
- hello_moto 16y agoLike um.... gasp Java?!
- eru 16y agoFor example, if a furctions get a file, they should make it clear whether it's the name of a file or a File-like object. Or whether both are acceptable. I don't know enough about Java documentation.
- tremendo 16y agoPHP's docs are good and bad in the same way that PHP itself is good and bad. For PHP the language reference is quick, easy, simple. Offers the syntax with required and optional parameters followed by a quick and typical use case. When that isn't sufficient, the comments may or may not have the exact use case you're looking for, many times they do. So it's all very convenient for drive-by-programming, like PHP. Good at quick'n'dirty, not so great for more involved, or for more carefully thought out solutions.
- eberfreitas 16y agoI think he is right. I never found a language with better docs! PHP's website is it's own documentation and it works really nice: http://php.net/arrays http://php.net/arrays http://php.net/extract http://php.net/extract http://php.net/oop http://php.net/oop I hardly memorize stuff 'cause it's so easy to look up to the docs that it's not necessary. And here is what you get when you don't really know what you are looking for: http://php.net/array_implode http://php.net/array_implode That is just nice documentation...
- Zak 16y agoHave a look at clojuredocs.org. I think it's one of the best documentation sites I've seen for any language or library. I especially like the inclusion of source code and links to other code that uses the thing being documented. An example: http://clojuredocs.org/clojure_core/clojure.core/condp http://clojuredocs.org/clojure_core/clojure.core/condp
- jhuni 16y agoI concur. That site's documentation is the best I have ever seen. The documentation on the main page is pretty good too: http://clojure.org/cheatsheet http://clojure.org/cheatsheet
- InclinedPlane 16y agoC#, Java, and other languages have abundant online documentation as well. What's more, their documentation isn't filled with the vagueness and ambiguity that plagues PHP's documentation.
- slig 16y agoIt's more like "Arguably the most used documentation for any language." As it's impossible to memorize the patternless names and random parameter order for similar functions.
- Joeri 16y agoThe parameter order is simple. String functions: haystack, needle. Array functions: needle, haystack. The naming however...
- edcrfv 16y agoHere's something that makes it easy for you to remember - from the PHP Manual - http://www.php.net/manual/en/faq.using.php#faq.using.parameterorder http://www.php.net/manual/en/faq.using.php#faq.using.paramet... 'Array function parameters are ordered as "needle, haystack" whereas String functions are the opposite, so "haystack, needle".'
- sigzero 16y agoIndeed. Python's is better and certainly Perl's is better.
- mkramlich 16y ago> that it's a endless pile of bullshit whose primary content is in user comments on the doc pages. I noticed that too, and it floored me.
- nsfmc 16y agoI think the other thing that's missing here is that there's nearly often a conflict between the actual behavior of a function and the overly optimistic documentation which is then amended by a series of caveats. I think i could forgive php more for behaving (and being named & structured) wildly inconsistently were it not that the documentation tries to make up for this by pretending this is actually not the case. So not only do you have this issue where the behavior of a function may be erratic but the documentation attempts to gloss over the issue by describing a function's most optimistic outcome rather than its actual behavior. Any behavioral caveats are left in the Notes section which in any other language documentation is reserved for "not thread safe" or "uses an easily guessable seed" or "execution blocks network access". Instead the Notes are used to explain "optional arguments not included change the behavior of this method to behave like this other one, but give no warning or otherwise visible indication of error." The whole "php is defensive programming" statement holds because you can't trust the documentation to be upfront about inconsistent behavior.