| The art of docblogging [message #2143] |
Wed, 30 July 2008 16:15  |
 mvriel
Messages: 20
Registered: July 2008
Location: Hoorn, the Netherlands |
Shiny and New |
|
|
Docblogging is the art of adding a certain type of comment to your code; comments which are called docblocks.
What is a docblock?
The docblock is a special type of comment which is used to identify the upcoming block of code as if describing an API call. These comments should be placed before a block of code. The following blocks are commonly docblogged,
- files, here we place the comments at the beginning of the file
- functions
- classes
- methods and
- class variables
A docblock commonly consists of a short description, a long description and annotations.
Usually class variable docblocks are a little more concise by only mentioning a short description and an annotation telling the reader about the type of variable.
You might be wondering at this point, what is an annotation? Well, you can think of an annotation as a variable or key/value pair contained inside a docblock, they aid in describing the code block which follows. Another way to view annotations is as tags or definitions of meta information.
An example
/**
* This is the short description, try to keep it one line.
* This is the long description, it may be used as an elaborate description how the code block functions
* and what to expect. As you can see, it may be multiple lines.
* @see docblock
* @param string $why
* @return string
*/
function aDocBlock($why)
{
[...]
}
As can be seen above, the function aDocBlock is described by giving it a title (the short description), telling a long story (the long description) and by providing annotations which add a tag-like extra description of the 'meta' information of the code block. There are several standard annotations which are used among PHP and Java developers, Some examples are given here.
@copyright, tell the reader who has copyright. Commonly used in the docblock at the start of a file
@var, the type and name of a class variable or method variable
@param, the type and name of a function variable
@return, the type of return value for a function or method
@author, who wrote this codeblock
and there are many more!
Docblocks are not only used by developers to help understand the code with which they are working. Also many applications can use this information to generate data during execution or provide feedback. For example, Eclipse PDT uses the @var, @param and @return to help identify when and which code completion suggestions to make. Some webservice platforms and Zend Studio can use comments to generate WSDL files.
But perhaps the biggest advantage is that phpDocumentor can generate API documentation from these comments, eliminating the need for you as a developer to write it.
Do yourself and your team a favor by docblogging, it really saves time!
@See phpDocumentor for more information on this subject.
|
|
|
| Re: The art of docblogging [message #2145 is a reply to message #2143 ] |
Wed, 30 July 2008 21:33  |
mweierophinney
Messages: 3
Registered: March 2007 |
Shiny and New |
|
|
I always include a section on docblocks when doing my Best Practices presentations. There are so many, many reasons to use them.
As you mention, some tools such as Studio can use them for generating type hints and WSDL. Many frameworks make use of them as well. Zend Framework uses them for all server classes; they're used to generate method signatures for XML-RPC, REST, JSON-RPC, and WSDL. PHPUnit utilizes special annotations such as @expectedException to help minimize the amount of code needed in a given test, and @group to allow running specific groups of tests.
They seem tedious at first... but if you are using an IDE, they're often stubbed out for you as you type. (Heck, in vim, there's even a phpdoc plugin that allows you to create them with a simple keystroke.) After a while, they become habit -- and good habits make for good code.
--
Matthew Weier O'Phinney
http://weierophinney.net/matthew/
|
|
|
| Re: The art of docblogging [message #2159 is a reply to message #2143 ] |
Sun, 03 August 2008 15:13 |
lig
Messages: 311
Registered: October 2006
Location: Fernandina Beach, Florida |
Feeling Comfortable |
|
|
another article on internal documenting -
--
life is a game... have fun
PHPCommunity
Open Source, Open Community
#phpc on Freenode
|
|
|
Members
Search
Help
Register
Login
Home
