5 ms·
http://us3.php.net/strstr http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd beha
by makmanalp 16y ago
http://us3.php.net/strstr http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd behavior, a gotcha, a pitfall, it's always in the comments. No need to trawl through blogs and mailing lists.
- kaerast 16y agoThe php docs are also nice in that it's really easy to work out a url to the document you need; it's almost always just php.net/functionname, and if it's not then you still get something useful.
- auxbuss 16y agoI agree, and have an additional comment: If the comments become part of the documentation, then you need to ruthlessly edit them to remove incorrect advice, duplication, and redundancy. If you simply leave everything there forever, then the comments become worthless. Integrity of information is everything.
- gabrielroth 16y agoAgreed. It would also be worth considering using Stack Overflow-style voting for comments.
- Nick_C 16y agoI loathe PHP's docs for two reasons: - the colour choice; - the comments. The colour choice for code examples is orange on gray. This is almost impossible to read for colour-blind people. I have to squint to make out each character. I can't get in to a flow and read the code, I have to decode each character then put them together to read the snippet in its entirety. I don't think user-land comments have any place in documentation. The docs form part of the official specs for the language and, personally, I find user comments create too much unintentional confusion. You often find well-intentioned amateurs make basic errors in PHP's doc examples. User comments can be great for examples, but they belong in a separate place, say, a wiki. An example of good docs IMO is Python's. A nice helpful topic bar on the left, and careful docs on the right.
- bmelton 16y agoPHP's comments are moderated, and I don't believe that a comment is even allowed on the page until it's passed at least some moderator's standards. That said, I think the comments absolutely belong there, as it's typically where I find the gotchas that don't make it into the language docs. Comments like "you can use this function most of the time, but if you're foo, functionB() is faster for those cases" are invaluable in optimization, and are seldom well-published in official language docs. What that means is that I can be a slow expert in the PHP language versus the years of experience it would take me to divine those truths working in another language.