Re: A bug, or not a bug...

[Sorry for the cross-post, but it made sense to me...] > Sometimes, trudging through the bug list, I come across things like > #5833 or #5123 (thats the ereg_replace bug and the terminating script > in comments bug). > Are they bugs or is it just the way things work? Without actually looking at these particular bugs... If the documentation doesn't say, and the user is doing something not specifically stated to "work", it's generally not considered a bug if what they get back is not what they expect. Exception: If it crashes PHP and/or some other software crashes or destroys vast amounts of data as an unexpected side effect, it's usually left as a bug, since that's just too nasty to leave in there. Any other behaviour is an "undocumented feature" which the coder may or may not decide to rely upon, but they risk that particular behaviour changing without notice in future releases, and they have no recourse to complaints (no bitchin' rights at all) if that breaks their software next week. If it seems to be an undocumented feature, then somebody who's high up in the PHP Development Team or the author who wrote the software and/or maintains the software needs to make a command decision if it's a "documented feature" or an "undocumented feature". It's nice sometimes to specifically state that "XXX is an undocumented feature", but the general rule is that if the docs don't say it will work, don't rely on it. One of the best language definitions ever, "Common Lisp, the Language" by Guy L. Steele, delineates this far better than I ever could. He even clearly defines two distinct phrases for kinds of errors: "An error is signaled if..." means that the software is supposed to generate an error message for the developer to handle. "It is an error to..." means that the developer who uses the function in such a way, regardless of whether it works that week or not, is at the mercy of the language developers should it crash in the next version. Obviously, that eventuality is generally to be avoided... But it is clearly stating that for all the possible inputs, the language is not even going to state what happens for this series of inputs, much less promise to give an error. I'd encourage everybody to quickly thumb through a copy at the bookstore and find the section where this discussion is laid out -- it's really quite remarkable in the sheer logic of what is planned out for documenting an extremely extensive language. PHP doesn't have the same kind of error-trapping mechanism, but documenting all the errors that could occur and what causes them, as opposed to things you could do that no claim is made about what will happen, would be a really big step forward for PHP as a language. Nailing down these sorts of things are what makes documentation *really* tight for an expericened coder to know that a lot of effort has gone into a well-defined language for every forseeable input. The point, though, is that there are a lot of under-documented "what-if" sort of things throughout PHP. A lot of these are implicit from the standpoint of PHP converting any string that doesn't even *look* like a number into 0, but there are some that are not quite so obvious... Of course I can't think of any off the top of my head, but I know I see "complaints" about such things on php-general from people who are, say, Perl hackers, which they claim has all this sort of stuff documented. (Not being willing to hurt my brain with terse-style Perl code, I wouldn't know personally...) But I do know that there are posts every once in a while that start off with "Yes, it's really dumb to do this, but PHP really shouldn't do XXX when I...." Or, "the documentation doesn't really say what should happen if I..." I think the first thing to be done might be to define the scale and scope of the PHP-DOC-QA effort -- Do you really want to nail down every detail of possible input and decide if the output is documented, a known error message, or simply an undefined behaviour, or is there some better meta-structure about how to define PHP's behaviour, or... Sorry if this is already an ongoing effort -- I'm not able to keep up with PHP-DOC, so I unsubscribed...