442 Chapter 22 Using PHP and MySQL for Large Projects code from other users that often answers the same questions you might have after read- ing the basic manual page.You can reach the English language version at http://www.php.net/manual/en/ Some programmers who come from a different language background might be tempted to write wrapper functions to essentially rename PHP’s functions to match the language with which they are familiar.This practice is sometimes called “syntactic sugar.” It’s a bad idea—it will make your code harder for others to read and maintain. If you’re learning a new language, you should learn how to use it properly. In addition, adding a level of function call in this manner will slow down your code.All things considered, this is an approach that should be avoided. If you find that the functionality you require is not in the main PHP library, you have two choices. If you need something pretty simple, you can choose to write your own function or object. However, if you’re looking at building a fairly complex piece of func- tionality—such as a shopping cart,Web email system, or Web forums—you won’t be sur- prised to find that these probably have already been built by somebody else. One of the strengths of working in the Open Source community is that code for application com- ponents such as these is often freely available. If you find a component similar to the one you want to build, even if it isn’t exactly right, you can look at the source code as a starting point for modification or for building your own. If you end up developing your own functions or components, you should seriously consider making them available to the PHP community when you have finished. This is the principle that keeps the PHP developer community such a helpful, active, and knowledgeable group. Writing Maintainable Code The issue of maintainability is often overlooked in Web applications, particularly because we often write them in a hurry. Getting started on the code, and getting it finished quickly sometimes seems more important than planning it first. However, a little time invested up front can save you a lot of time further down the road when you’re ready to build the next iteration of an application. Coding Standards Most large IT organizations have coding standards—guidelines to the house style for choosing file and variable names, guidelines for commenting code, guidelines for indent- ing code, and so on. Because of the document paradigm often previously applied to Web development, coding standards have sometimes been overlooked in this area. If you are coding on your own or in a small team, it’s easy to underestimate the importance of coding standards. Don’t do it because your team and project might grow.Then you will not only end up 28 525x ch22 1/24/03 3:38 PM Page 442 443 Writing Maintainable Code with a mess on your hands, but also a bunch of programmers who can’t make heads or tails of any of the existing code. Naming Conventions The goals of defining a naming convention are n To make the code easy to read. If you define variables and function names sensibly, you should be able to virtually read code as you would an English sentence, or at least pseudocode. n To make identifier names easy to remember. If your identifiers are consistently for- matted, it will be easier to remember what you called a particular variable or func- tion. Va r iable names should describe the data they contain. If you are storing somebody’s sur- name, call it $surname.You need to find a balance between length and readability. For example, storing the name in $n will make it easy to type, but the code will be difficult to understand. Storing the name in $surname_of_the_current_user is more informa- tive, but it’s a lot to type (easier to make a typing error) and doesn’t really add that much. You need to make a decision on capitalization.Variable names are case sensitive in PHP, as we’ve mentioned before.You need to decide whether your variable names will be all lowercase, all uppercase, or a mix, for example, capitalizing the first letters of words. We tend to use all lowercase, as it’s the easiest thing to remember. It’s also a good idea to distinguish between variables and constants with case—a com- mon scheme is to use all lowercase for variables (for example, $result) and all uppercase for constants (for example, PI). One bad practice some programmers use is to have two variables with the same name but different capitalization, just because they can, such as $name and $Name for instance. I hope it is obvious why this is a terrible idea. It is also best to avoid amusing capitalization schemes such as $WaReZ because no one will be able to remember how it works. You should also think about what scheme to use for multiword variable names. For example: $username $user_name $UserName are all schemes I have seen used. It doesn’t matter which you opt for, but you should try to be consistent about this.You might also want to set a sensible maximum limit of two to three words in a variable name. Function names have many of the same considerations, with a couple of extras. Function names should generally be verb oriented. Consider built-in PHP functions such as addslashes() or mysql_connect(),which describe what they are going to do 28 525x ch22 1/24/03 3:38 PM Page 443 444 Chapter 22 Using PHP and MySQL for Large Projects to or with the parameters they are passed.This greatly enhances code readability. Notice that these two functions have a different naming scheme for dealing with multiword function names. PHP’s functions are inconsistent in this regard, presumably partly as a result of having been written by a large group of people, but mostly because many func- tion names have been adopted unchanged from various different languages and APIs. Also remember that function names are not case sensitive in PHP.You should proba- bly stick to a particular format anyway, just to avoid confusion. You might want to consider using the module naming scheme used in many PHP modules, that is, prefixing the name of functions with the module name. For example, all the MySQL functions begin with mysql_, and all the IMAP functions begin with imap_.If, for example, you have a shopping cart module in your code, you could prefix the function in that module with cart_. In the end, it doesn’t really matter what conventions and standards you use when writing code, as long as some consistent guidelines are applied. Commenting Your Code All programs should be commented to a sensible level.You might ask what level of com- menting is sensible. Generally you should consider adding a comment to each of the fol- lowing items: n Files, whether complete scripts or include files. Each file should have a comment stating what this file is, what it’s for, who wrote it, and when it was updated. n Functions. Function comments should specify what the function does, what input it expects, and what it returns. n Classes. Comments should describe the purpose of the class. Class methods should have the same type and level of comments as any other function. n Chunks of code within a script or function. I often find it useful to write a script by beginning with a set of pseudocode style comments and then filling in the code for each section. So an initial script might resemble this: <? // validate input data // send to database // report results ?> This is quite handy because after you’ve filled in all the sections with function calls or whatever, your code is already commented. n Complex code or hacks.When it takes you all day to do something, or you have to do it in a weird way, write a comment explaining why you did it that way.This way, when you next look at the code, you won’t be scratching your head and thinking,“What on earth was that supposed to do?” 28 525x ch22 1/24/03 3:38 PM Page 444 445 Writing Maintainable Code Another general guideline to follow is that you should comment as you go.You might think you will come back and comment your code when you are finished with a proj- ect. I guarantee you this will not happen, unless you have far less punishing development timetables and more self-discipline than we do. Indenting As in any programming language, you should indent your code in a sensible and consis- tent fashion. It’s like laying out a resumé or business letter. Indenting makes your code easier to read and faster to understand. In general, any program block that belongs inside a control structure should be indented from the surrounding code.The degree of indenting should be noticeable (that is, more than one space) but not excessive. I generally think the use of tabs should be avoided.Although easy to type, they consume a lot of screen space on many people’s monitors.We use an indent level of two to three spaces for all projects. The way you lay out your curly braces is also an issue.The two most common schemes are as follows: Scheme 1: if (condition) { // do something } Scheme 2: if (condition) { // do something else } Which one you use is up to you.The scheme you choose should (again) be used consistently throughout a project to avoid confusion. Breaking Up Code Giant monolithic code is awful. Some people will have one huge script that does every- thing in one main line of code. It is far better to break up the code into functions and/or classes and put related items into include files.You can, for example, put all your database-related functions in a file called dbfunctions.php. Reasons for breaking up your code into sensible chunks include the following: n It makes your code easier to read and understand. n It makes your code more reusable and minimizes redundancy. For example, with the previous dbfunctions.php file, you could reuse it in every script in which you need to connect to your database. If you need to change the way this works, you have to change it in only one place. 28 525x ch22 1/24/03 3:38 PM Page 445 446 Chapter 22 Using PHP and MySQL for Large Projects n It facilitates teamwork. If the code is broken into components, you can then assign responsibility for the components to team members. It also means that you can avoid the situation in which one programmer is waiting for another to finish working on GiantScript.php so that she can go ahead with her own work. At the start of a project, you should spend some time thinking about how you are going to break up a project into planned components.This requires drawing lines between areas of functionality, but don’t get bogged down in this as it might change after you get going on a project.You will also need to decide which components need to be built first, which components depend on other components, and the time line for developing all of them. Even if all team members will be working on all pieces of the code, it’s generally a good idea to assign primary responsibility for each component to a specific person. Ultimately this would be the person who is responsible if something goes wrong with her component. Someone should also take on the job of build manager—that is, the per- son who makes sure that all the components are on track and working with the rest of the components.This person usually also manages version control—we’ll talk about this more later in the chapter.This person can be the project manager, or it can be allocated as a separate responsibility. Using a Standard Directory Structure When starting a project, you need to think about how your component structure will be reflected in your Web site’s directory structure. Just as it is a bad idea to have one giant script containing all functionality, it’s usually a bad idea to have one giant directory con- taining everything. Decide how you are going to split it up between components, logic, content, and shared code libraries. Document your structure and make sure that every- body working on the project has a copy so that they can find things.This leads in to the next point. Documenting and Sharing In-House Functions As you develop function libraries, make them available to other programmers in your team. Commonly, every programmer in a team writes her own set of database, date, or debugging functions.This is a time waster. Make functions and classes available to others. Remember that even if code is stored in an area or directory commonly available to your team, they won’t know it’s there unless you tell them. Develop a system for docu- menting in-house function libraries, and make it available to programmers on your team. Implementing Version Control Ve rsion control is the art of concurrent change management as applied to software development.Version control systems generally act as a central repository or archive and 28 525x ch22 1/24/03 3:38 PM Page 446 . Consider built-in PHP functions such as addslashes() or mysql_ connect(),which describe what they are going to do 28 525x ch22 1/24/03 3:38 PM Page 443 444 Chapter 22 Using PHP and MySQL for Large. come back and comment your code when you are finished with a proj- ect. I guarantee you this will not happen, unless you have far less punishing development timetables and more self-discipline. application. Coding Standards Most large IT organizations have coding standards—guidelines to the house style for choosing file and variable names, guidelines for commenting code, guidelines for indent- ing