(^58) CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS
function notimportant{}
/*
This is a doccomment but it is not associated with the function
/
function notimportant() {}
As you can see, doccomments are picky. If they are not placed immediately before the
function, they will not be associated with that function.
Now you can write and associate doccomments, but what does that association actually do?
There is a key distinction between a normal comment and a doccomment. To understand
that distinction, you need a little background on how the PHP parsing process works.
Lexing.
While PHP is not a compiled language, it resembles compiled languages in that PHP code is
converted into a binary format before actually being executed.
This transformation from programming language to executable code is called lexing because
it transforms the lexical structure of PHP code into opcodes (numeric representations of PHP
language elements). When the lexer—the part of PHP that performs lexing—encounters a
normal comment, it understands that it is a comment and ignores it, discarding all the data
within the comment. All discarded data is no longer present in the resulting binary format and
cannot be accessed by other programs; therefore, regular comments aren’t useful for embeddingMetadata
On the other hand, a doccomment, like a function or class, is actually parsed and its data
stored. It becomes part of the binary, and more important, when declared with a code element,
becomes associated with that element. It is this association that is so critical for creating context for
your data.
The context of comments is important because metadata is accessed by asking the program
for the element’s details and then checking the associated doccomment property. Without the
association, you won’t be able to use your doccomments in a programmatic way, and you might as
well have just used a normal multiline comment.
The association of doccomments and programming elements provides the ability to embed
extra metadata in your programs.Metadata
Metadata is data that describes other data. In programming terms, that means metadata is
information about your program. For example, all the method names within a class can be
considered metadata.
By default, PHP includes metadata for most programming elements. However, you may
need to embed more metadata than PHP normally does. For example, some systems use meta-
data attributes to include testing information, such as the expected output for a certain input.
While some other languages inherently support addition of extra metadata through program-
ming elements called attributes, PHP doesn’t include this ability. However, this ability can be
simulated with the parsing of doccomments. For example, you can embed metadata that is not
important to the execution of the application but is important to the creation of a manual
about that code.McArthur_819-9C06.fm Page 58 Friday, February 22, 2008 8:59 AM