Page 1 of 2
Abstraction Class Interfaces: DB, Template, etc.
Posted: Wed Aug 25, 2004 8:36 pm
by Christopher
One good and bad thing about PHP is the large number of competing DB abstraction layers, template libraries, etc. I just wish they used more similar interfaces. Most of the differences are trivial. I understand that different capabilities need specific functions, but if the basic functions had the same names it would allow programmers to compare and choose the right lib for each project.
Examples:
db::query vs db::execute vs db::exec
template::assoc vs template::assign vs template::set
template::display vs template::show
template::fetch vs template::toHTML
error::isError vs error::errorNo
error::errorMsg vs error::getMessage
As you can see, a lot of this is just trivial programmer opinion. Many of these, such as display/show, toHTML, isError, errorMsg/getMessage can be used in many different types of classes. I think it would be a great service to the PHP community if we started to standardize some of these.
I care more about useful standards than my opinion in basic stuff like this. I note from looking at projects code and reading the leading PHP books that there is 98% agreement on things like formatting PHP code. So why not these basic function and variable names?
I would be interested is people giving examples of common, competing function and variable names and what people think the standard names should be.
Posted: Wed Aug 25, 2004 9:24 pm
by feyd
different programmers, different schools of thought..
hell.. there are huge debates over how to set up function names:
fileGetContents, file_get_contents, file_getContents, FileGetContents you can flip the case of those all day adding in and removing underscores... each of the combinations can come from differing schools of thought, the age of the programmer, the years in which they first learned programming.. all sorts of things..
Posted: Thu Aug 26, 2004 2:00 am
by Christopher
Well, I agree that are some different styles. However I don't think there is as much variation or significant disagreement as you say there is. With some exceptions most php functions use underscores and most class methods use studly caps. PHP5 even standardizes on that.
As for your: fileGetContents, file_getContents, FileGetContents. I have a couple of responses:
First, I have a hard time getting very excited about these honestly tiny differences. I know there are those programmers get upset by things as trivial as this, but most programmers are generally flexible.
Second, I would consider the above three names to be the same and they would satisfy what I am looking for. They all consistently use the words get, file and contents. My point was that if some libraries use getContents and others use loadData then it is confusing. I am looking for guidelines for when, for example, to use load, get or fetch. Do we use load for files, get for variables, and fetch for databases? If so then loadContents, LoadContents or load_contents are all fine with me.
Third, some things are structural. PEAR uses the underscore for directory/namespace reasons. As more libraries use the PEAR installer that standard will necessarily follow -- so why fight it. Everyone using the PEAR installer will be a positive for the PHP community.
Finally, I don't think you point matters much for things like fetch vs exec or display vs show. These are the boring function names and it makes sense for them to be consistent across PHP libraries. The specific functions in a library will obviously vary more library to library.
My goal is not to dictate to anyone, especially those programmers who get very excited about capitalization. My thought was that if we as a community move toward some general guidelines for these commonly used nouns and verbs, we will all benefit.
Posted: Thu Aug 26, 2004 2:35 am
by timvw
Posted: Thu Aug 26, 2004 4:32 am
by Christopher
I agree that PDO is great, but whether PDO is great has nothing to do with my point. In fact, PDO has a good example of what I am talking about. In PDO you do the following:
$db = new PDO(...);
$statement = $db->prepare("select ...");
$statement->execute($array_of_values_for_prepare);
Notice that it uses the function name is "execute" not "query" like PEAR and all of the PHP database libraries (except Oracle which uses "exec"). My question to the PDO guys is -- why make it different? To further confuse the issue, many databases use the term "execute" to run stored procedures. That makes sense because "execute" to me means run code. The PDO execute is actually a parse then a query, but the query is the main action not the parse.
Maybe some Java or Perl libs use execute, but that's no reason to be inconsistent with the existing PHP standards. We can do better.
More standard and consistent would be:
$db = new PDO(...);
$db->query("select ..."); // unprepared SQL
and
$statement = $db->prepare("select ...");
$statement->query($array_of_value_for_prepare);
PDO is still alpha so it's not too late to improve this.
Posted: Tue Sep 14, 2004 9:16 am
by timhortons
PHP has recently changed a lot of their postgre functions to conform to the rest of PHPs function name setup, which i think is a good idea. so at least somethings still conforming
personally, i like the idea that function names in PHP aren't case sensitive, eg: you could use getimagesize() or getImageSize() so it's the same function, but gives the programmer more choice about how they like function names, i like functions as clear as possible, so in many of mine, i use underscores between words, eg: db_connect()
I think that with all the libraries available, that there should be some sort of "naming convention" or something so that you're not continually digging around in documentation looking for the correct name for a function or whatever...
Posted: Wed Sep 15, 2004 4:08 pm
by Christopher
What I am interested in is some consistency in the simple verbs and nouns that are used for common functon/method names. I don't mind if it's db_connect, DBConnect or db_Connect. I'm not up to fighting any silly formatting battles. It's oddball naming I notice like db::open(), db::choose, db::execute() rather than db::connect(), db::select, db::query() which are the common PHP usage. I gave more examples above.
I think there woul be a number of benefits:
- To provide some guidelines when you need to roll your own classes.
- To make it easier to convert from one library to another.
- To uncover the real differences between the plethora of similar libraries out there.
- To provide consistency for similar functions (e.g. isError(), getMessage(), toHTML() ) in different types of classes.
Does anyone have any lists or is there a source for PHP standards like this?
Posted: Wed Sep 15, 2004 6:01 pm
by McGruff
A range of names can be very confusing when you're learning. Trouble is, if you gathered a dozen people in a room to sort it out you'd get at least 13 different opinions.
It's not possible, I think, in the anarchic world of php. Not to mention that a programming standard would really have to apply to all languages, making the task even harder.
Posted: Wed Sep 15, 2004 7:48 pm
by Christopher
I definitely hear this a lot:
Trouble is, if you gathered a dozen people in a room to sort it out you'd get at least 13 different opinions.
However, I think if you really gathered a dozen PHP programmers in a room to sort it out, you'd have one guy who's opinion would be very different and could not be changed. The other 11 would be divided into 2-3 groups of slightly different opinions (like underscores vs. caps) and they could probably easily agree on some general standards.
I just don't think that most programmers care that much whether it is
display() or
show(), and would be glad for the benefits some consistency would bring.
Posted: Wed Sep 15, 2004 9:50 pm
by McGruff
I do agree with you about standards. I wish it could happen.
Posted: Thu Sep 16, 2004 3:10 am
by Christopher
I don't think the PHP community wants dictated naming standards. But I think most PHP programmers would agree that some guidelines for a lot of the common function names would help everyone from newbies to library maintainers.
Has anyone done a survey of similar classes to see if there any standards fall out? Or has PEAR, PHP5 or any of the frameworks given any guidelines for the verbs/nouns to use for common function names?
Posted: Thu Sep 16, 2004 11:00 am
by feyd
Piece of advice: if a language doesn't support naming convention, do not try to impose it on other programmers. It'll backfire 9 times out of 10. Unless these programmers were originally taught in the naming convention, it's practically a waste of time trying to get a standard of naming out and used.
Recommendations can be published, but I seriously doubt it'd ever take hold in our generation of programmers.
Posted: Thu Sep 16, 2004 12:47 pm
by timvw
At the university where i work/study they have come up with
https://ludit.kuleuven.be/pahupa/
But haven't really seen well-defined interfaces/methods.
Posted: Fri Sep 17, 2004 2:05 pm
by Christopher
I took a look at PaHuPa, and its
Naming section is a good example of what I am NOT interested in, and what I think
feyd is reacting to. Underscores and capitalization really don't matter to me. That's more a project thing. Another example is:
http://pear.php.net/manual/en/standards.naming.php.
Piece of advice: if a language doesn't support naming convention, do not try to impose it on other programmers. It'll backfire 9 times out of 10. Unless these programmers were originally taught in the naming convention, it's practically a waste of time trying to get a standard of naming out and used.
Recommendations can be published, but I seriously doubt it'd ever take hold in our generation of programmers.
My goal is not to dictate to anyone. I don't see how it could backfire because most PHP programmers already use very similar words. They're not going to stop naming functions "query()" because it is in a guideline. But it might help newbies to know what a lot of the standard interfaces are.
I am looking for some guidelines for things like:
- When dealing with files when to use words like: open, close, read, write, load, save. Are load/save for dealing wth the whole file and read/write for chunks?
- For databases, are the basic names something like: connect, select, query, prepare, execute?
- For template systems is it show or display, toHTML or fetch? And how do you decide. WIth things like show/display do you just go with the shorter one always? With toHTML/fetch do you use toHTML because fetch is used for databases?
- For errors, what is the name of the function that returns an error string? That returns an error number? That checks if an error occured?
- For exceptions should the names all end with the word
Exception[/n]. For example see: http://pear.php.net/pepr/pepr-proposal-show.php?id=132
I just think that guideines for common words are more useful than things like underscores and capitalization which get specified all the time.
Again, does anyone know if there are any written standards for this (even outside PHP)?
Posted: Fri Sep 17, 2004 2:29 pm
by feyd
there are published OOP styles and there's always Hungarian notation.. although that's the opposite direction of OOP.