phpdoc as code duplication

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

koen.h
Forum Contributor
Posts: 268
Joined: Sat May 03, 2008 8:43 am

phpdoc as code duplication

Post by koen.h »

I wonder why so many people use phpdoc blocks before class methods or variables. To me they seem like code duplication. A question for those who use them: why do you? What reason could want me to create them?
User avatar
s.dot
Tranquility In Moderation
Posts: 5001
Joined: Sun Feb 06, 2005 7:18 pm
Location: Indiana

Re: phpdoc as code duplication

Post by s.dot »

To create professional documentation from the source code using phpdocumentor
Set Search Time - A google chrome extension. When you search only results from the past year (or set time period) are displayed. Helps tremendously when using new technologies to avoid outdated results.
User avatar
VladSun
DevNet Master
Posts: 4313
Joined: Wed Jun 27, 2007 9:44 am
Location: Sofia, Bulgaria

Re: phpdoc as code duplication

Post by VladSun »

To have editors recognize parameter/property/return value types, etc. ...
There are 10 types of people in this world, those who understand binary and those who don't
User avatar
Eran
DevNet Master
Posts: 3549
Joined: Fri Jan 18, 2008 12:36 am
Location: Israel, ME

Re: phpdoc as code duplication

Post by Eran »

To explain the purpose of the function and its parameters to maintainers / target audience
User avatar
pickle
Briney Mod
Posts: 6445
Joined: Mon Jan 19, 2004 6:11 pm
Location: 53.01N x 112.48W
Contact:

Re: phpdoc as code duplication

Post by pickle »

I get paid per line, so...



(kidding of course)
Real programmers don't comment their code. If it was hard to write, it should be hard to understand.
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: phpdoc as code duplication

Post by josh »

I agree with you, its duplication in most circumstances. A unit test is much better thing to write if you want to be professional, it cannot become out of date, and it documents the code a lot better.
User avatar
Jonah Bron
DevNet Master
Posts: 2764
Joined: Thu Mar 15, 2007 6:28 pm
Location: Redding, California

Re: phpdoc as code duplication

Post by Jonah Bron »

josh wrote:I agree with you, its duplication in most circumstances. A unit test is much better thing to write if you want to be professional, it cannot become out of date, and it documents the code a lot better.
But it's a must if you want to generate extracode documentation, no?
User avatar
Zyxist
Forum Contributor
Posts: 104
Joined: Sun Jan 14, 2007 10:44 am
Location: Cracow, Poland

Re: phpdoc as code duplication

Post by Zyxist »

Several reasons:

1. When using editors, they show phpdoc block contents, not the function/method body, so this is the way to say, how to use them. And if the project is big, don't think you'll remember everything.
2. Editors can recognize return and parameter types using the information from phpdoc.
3. English and any other spoken language will always be more expressive than any other programming language. If you speak about dummy websites, where there are actually no algorithms, but most of the methods are getters, setters and ORM hooks, then yes - it's perfectly visible, what they do, and such phpdoc would be a code duplication. But there are programmers who do not write only dummy websites, but complex libraries, or use advanced algorithms. In these cases, code is not very helpful. You see that it calculates something, but what it is, why it is and what's the idea behind the algorithm implementation - it is not visible at the first sight. phpDoc is the best way to explain some issues, and describe, what data formats are accepted etc.

Of course, it also depends on the programmers, how useful phpdoc comments will be. For example, in Zend Framework many comments look like this:

Code: Select all

/**
 * Performs ABCX calculation.
 */
public function performABCXCalculation()
{
  // ...
}
If all the authors are able to write is repeating the method name, they'd do better if they gave up commenting. Sometimes I'd like to see some more information explaining what it is, how to use it and what to do with the result, because it is not obvious for other programmers than the authors. Such issues are not clearly visible at the first sight and phpdoc comments are the best place where we can document it.

I have a similar opinion about unit tests. They can verify the correctness of the program but using them as a documentation has the same drawback, as reading the information from the code: it is actually a reverse engineering and guessing: "ok, I know that this method produces this result for these data, but what's next? Why is this useful for me?"
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: phpdoc as code duplication

Post by josh »

I don't desire 'extra-code documentation' or 'overriding the code hints' here is why:

1 - code completion already works. Using a docblock to get code completion can lie to me, because the docblock can be out of date (a unit test cannot)

2 - If a method cannot be understood from it's name, a 5 word description is not going to help at all (this is where a unit test whoops a comment's butt. It shows the relationship between inputs & outputs, which a comment cannot show.) An 3 line example code is worth a 1,000 word English paragraph. Ever notice when reading certain documentations its always the 'examples' that makes it click in your head? When exchanging ideas on forums and someone doesn't understand, they always ask for 'examples' to clarify. Examples are the king of all documentation.

3 - I can still generate 'extra-code documentation' that shows all the methods on my class. In fact I don't have to 'generate' anything, the tests are already the better form of documentation.

4 - @ Xyonist - "can't remember anything" - this is true, but if you can't remeber the name of a method, code completion isn't going to pop up the docblock. You end up opening the class & browsing it's methods, or asking phpdoc to 'generate' and waiting 2hrs for updated documentation. I'd rather just pull out grep, or read the unit test.

I find it ironic so many developers will readily type 2x as much code, simply because the practice is so ingrained in our brains. But they use the same reason as an excuse not to write unit tests (it takes 2x as much code).

Now docbook is a big difference than docblock, for example docbook just generates chapters of text, like the PHP manual. That kind of documentation is useful. Simply re-stating the names of my methods detracts from development. English descriptions of stuff doesn't belong in the production code. Yes it makes it easier to find the documentation for you to edit it, but you're making it next to useless for the consumer of that documentation, in my opinion. For example Zend's phpdoc's are of small use. I used them sometimes but eventually found it faster just to look at the code itself when I'm trying to find a method. No internet delay that way. If I don't know how a method works, generally I find the phpdocblock's not useful - I always have to go to the online 'reference guide' and read the extended description, look at the unit tests, or scrutinize the production code. In hindsight the docblock's were more than useless. They detract from development, extra code that can become 'out of date', extra scrolling within your classes, extra reasons to procrastinate (as if we needed any outside of this forum) etc..
User avatar
Jonah Bron
DevNet Master
Posts: 2764
Joined: Thu Mar 15, 2007 6:28 pm
Location: Redding, California

Re: phpdoc as code duplication

Post by Jonah Bron »

I agree that the comments have very limited use (if any at all) in the source itself. But if I'm using some sort of API or library, I'd much rather have a list of functions and descriptions of their purpose/behavior than being required to scan through the source code. I have found this to be a necessity working with Java (http://download.oracle.com/javase/1.4.2 ... mmary.html). Not sure... is this what you're saying?
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: phpdoc as code duplication

Post by alex.barylski »

I have long thought phpDoc comments were something annoying to say the least. However when I realized Eclipse picks up those ocmments and displays them in a tooltip my opion changed instantly. It's really nice stepping through code and mousing over a method and getting the lowdown without having to refer to the API docs themselves or open the file, etc.
User avatar
VladSun
DevNet Master
Posts: 4313
Joined: Wed Jun 27, 2007 9:44 am
Location: Sofia, Bulgaria

Re: phpdoc as code duplication

Post by VladSun »

Netbeans does this tolltip thing too.
There are 10 types of people in this world, those who understand binary and those who don't
User avatar
Jenk
DevNet Master
Posts: 3587
Joined: Mon Sep 19, 2005 6:24 am
Location: London

Re: phpdoc as code duplication

Post by Jenk »

My class and method names do all the documenting needed. I haven't used a comment longer than one sentance in a very long time, and even then it's to explain a 'What the hell?' moment because of some bizarre behaviuor due to underlying framework oddity (as is the case with a lot of .NET WCF) or because the client has put a bizarre requirement in an interface design.

If you need a comment block to explain what a method does, it's doing to much. A method should have one responsibility/behaviiour trait, and no more. In fact scrub that, a class should only have one responsibility.
User avatar
VladSun
DevNet Master
Posts: 4313
Joined: Wed Jun 27, 2007 9:44 am
Location: Sofia, Bulgaria

Re: phpdoc as code duplication

Post by VladSun »

Jenk wrote:If you need a comment block to explain what a method does, it's doing to much. A method should have one responsibility/behaviiour trait, and no more. In fact scrub that, a class should only have one responsibility.
I rarely have "description" comments, but I tend to put @return, @param, @property phpdocs. E.g.:

Code: Select all

/**
 * @property Collection_Model model
 */
class Collection_Controller extends Controller
{
	protected $model		= null;
or

Code: Select all

class Error 
{
	/**
	 * @param  string|array $msg
	 * @return bool
	 */
	public function register($msg)
	{
		if (!is_array($msg))
		{
			$msg = array($msg);
		}
		....
	
There are 10 types of people in this world, those who understand binary and those who don't
User avatar
Jenk
DevNet Master
Posts: 3587
Joined: Mon Sep 19, 2005 6:24 am
Location: London

Re: phpdoc as code duplication

Post by Jenk »

Those I can understand, but that can still be negated by using more descriptive names such as aCollectionModel or such to describe the expected parameter or property type.
Post Reply