3 ms·
The comments are only needed because the documentation is often wrong or confused. And, of course, usually most of the comments are wrong too. Other languages
by ptx 8y ago
The comments are only needed because the documentation is often wrong or confused. And, of course, usually most of the comments are wrong too.
Other languages don't need comments because they at least aim to have documentation that's correct.
- chiefalchemist 8y agoI don't see it that way. The comments are there to prevent others from re-inventing the wheel, to share insights, etc. Yes, sometimes that also highlights a "bug" or some other "flaw" but that's the rare exception. Maybe it would help if you listed some links to language docs that you feel the rest should use as benchmarks?
- chx 8y agoIf you find the documentation wrong or confused please let us know. https://bugs.php.net/ https://bugs.php.net/ We do our best. I was granted access some ten years ago and whenever I find a confusing page I fix it. I know there has been terrible pieces before but for the last oh five or six years I don't really find anything too bad. Please let us know what you found wrong. Thanks!
- ptx 8y agoI was mostly responding to the idea in an ancestor comment that PHP has unusually good documentation (better than that of other languages), "best of all" having comments. I'm sure the PHP documentation is getting better all the time! Other languages also have good documentation, though. And as pushpop said in an earlier comment, the reason that the comments were useful historically is that the documentation was not always correct or complete. (Perhaps in part because the the language used to have a lot more unintended quirks?)
- welly 8y ago"Often wrong"? Really? By often, 50% more wrong than right or less? Or more? I can count on one hand the number of occasions I've found the documentation to be incorrect.
- pushpop 8y ago"Often" is a fuzzy term and it's used subjectively here. It doesn't mean "most of the documentation" (which would be the >50% goal post you're driving at). It simply means "a lot of the time $OP checks the docs". It might be the case that the only time they need to check the docs is for some of the more advanced features of PHP where errors are more likely to be found in the docs. While you could correctly argue "selection bias", it doesn't still take away from the OPs perspective that it often happens to him.