55■ ■ ■
CHAPTER 6
Documentation and
Coding Conventions
Documentation is a crucial part of software development. It provides information regarding
how to use the program, and can also help future maintainers and consumers of your program
understand the decisions you made while developing the application. Documentation can also
help you to remember design decisions you made when you later revisit your applications.
Documentation’s importance is not limited to the communication of ideas. In PHP, docu-
mentation is also a key way to include metadata in your applications. Metadata, or data about
data, is a key way to create advanced interactions between objects when you do not know the
details of the objects beforehand. It’s also a handy way of self-documenting applications that
can be parsed into manuals automatically.
In this chapter, I will explain some of the common formats for PHP documentation,
including PHPDoc and DocBook. These industry-standard formats, when correctly applied,
will allow you to create easy-to-read code, generate manuals, and embed metadata in your
applications. Note that you will need to understand the information presented in this chapter
to take advantage of the powerful reflection features covered in the next chapter.Coding Conventions
Coding conventions can be troublesome. Many developers have conducted lengthy arguments
about why their way is the best way and any other methods are inferior. Although opinions on
the subject may differ, one idea is universally accepted: consistency is king. Correctness is
entirely in the eye of the beholder, but agreement is crucial. It’s critically important that all
members of a team follow the same conventions and apply them consistently. Most of the
public projects, such as the Zend Framework and PEAR components, have clearly defined
coding standards.
The sort of conventions I’m referring to are pretty basic. For the most part, they deal with
where braces go and how functions and variables are named. They also include various docu-
mentation standards that will be discussed shortly.
For example, some developers like to put an opening brace on the same line as an element,
like this:function foo() {
}McArthur_819-9C06.fm Page 55 Friday, February 22, 2008 8:59 AM