What Makes Up a Good Name

1. Use full English descriptors that accurately describe the variable/field/class/... For example, use names like firstName, grandTotal, or CorporateCustomer. Although names like x1, y1, or fn are easy to type because they are short, they do not provide any indication of what they represent and result in code that is difficult to understand, maintain, and enhance (Nagler, 1995; Ambler, 1998).
2. Use terminology applicable to the domain. If your users refer to their clients as customers, then use the term Customer for the class, not Client.
3. Use mixed case to make names readable. You should use lower case letters in general, but capitalize the first letter of class names as well as the first letter of any non-initial word (Kanerva, 1997).
4. Use abbreviations sparingly, but if you do so then use them intelligently. This means you should maintain a list of standard short forms (abbreviations), you should choose them wisely, and you should use them consistently. For example, if you want to use a short form for the word "number", then choose one of "nbr", "no", or "num", document which one you chose and use only that one.
5. Avoid long names (< 15 characters is a good idea). Although the class name PhysicalOrVirtualProductOrService might seem to be a good class name at the time, this name is simply too long and you should consider renaming it to something shorter, perhaps something like Offering (NPS, 1996).
6. Avoid names that are similar or differ only in case. For example, the variable names persistentObject and persistentObjects should not be used together, nor should anSqlDatabase and anSQLDatabase (NPS, 1996).
7. Capitalize the first letter of standard acronyms. Names will often contain standard abbreviations, such as SQL for Standard Query Language. Names such as sqlDatabase for an attribute, or SqlDatabase for a class, are easier to read than sQLDatabase and SQLDatabase.

Good Documentation

1. Comments should add to the clarity of your code. The reason why you document your code is to make it more understandable to you, your coworkers, and to any other developer who comes after you (Nagler, 1995). If your program isn't worth documenting, it probably isn't worth running (Nagler, 1995).
2. Avoid decoration, i.e. do not use banner-like comments. It is a major waste of time that add a little value to the end product. You want to write clean code, not pretty code.
3. Keep comments simple. Some of the best comments I have ever seen are simple, point-form notes. You do not have to write a book, you just have to provide enough information so that others can understand your code.
4. Write the documentation before you write the code. The best way to document code is to write the comments before you write the code. This gives you an opportunity to think about how the code will work before you write it and will ensure that the documentation gets written. Alternatively, you should at least document your code as you write it. Because documentation makes your code easier to understand you are able to take advantage of this fact while you are developing it. The way I look at it, if you are going to invest the time writing documentation you should at least get something out of it (Ambler, 1998).
5. Document why something is being done, not just what. Fundamentally, I can always look at a piece of code and figure out what it does. (Ambler, 1998).

Three Types of Comments

As in Java, PHP has three styles of comments:

• Documentation comments start with /** and end with */. Use documentation comments immediately

before declarations of classes, member functions, and fields to document them. Documentation comments are processed by phpdoc to create external documentation.

/** Customer – A customer is any
person or organization that we sell
services and products to @author S.W. Ambler */

• C-style comments which start with /* and end with */. Use C-style comments to document out lines of code that are no longer applicable, but that you want to keep just in case your users change their minds, or because you want to temporarily turn it off while debugging.

/* This code was commented out by
J.T. Kirk on Dec 9, 2007 because it
was replaced by the preceding code.
Delete it after two years if it is still not
applicable. . . . (the source code ) */

• single-line comments that start with // and go until the end of the source-code line. Use single line comments internally within member functions to document business logic, sections of code, and declarations of temporary variables.

// Apply a 5% discount to all invoices
// over $1000 as defined by the Doe's
// generosity campaign started in 
// Feb. 2007.