phpdoc as code duplication
Moderator: General Moderators
phpdoc as code duplication
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?
Re: phpdoc as code duplication
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.
Re: phpdoc as code duplication
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
Re: phpdoc as code duplication
To explain the purpose of the function and its parameters to maintainers / target audience
Re: phpdoc as code duplication
I get paid per line, so...
(kidding of course)
(kidding of course)
Real programmers don't comment their code. If it was hard to write, it should be hard to understand.
Re: phpdoc as code duplication
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.
- Jonah Bron
- DevNet Master
- Posts: 2764
- Joined: Thu Mar 15, 2007 6:28 pm
- Location: Redding, California
Re: phpdoc as code duplication
But it's a must if you want to generate extracode documentation, no?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.
Re: phpdoc as code duplication
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:
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?"
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()
{
// ...
}
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?"
Re: phpdoc as code duplication
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..
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..
- Jonah Bron
- DevNet Master
- Posts: 2764
- Joined: Thu Mar 15, 2007 6:28 pm
- Location: Redding, California
Re: phpdoc as code duplication
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
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.
Re: phpdoc as code duplication
Netbeans does this tolltip thing too.
There are 10 types of people in this world, those who understand binary and those who don't
Re: phpdoc as code duplication
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.
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.
Re: phpdoc as code duplication
I rarely have "description" comments, but I tend to put @return, @param, @property phpdocs. E.g.: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.
Code: Select all
/**
* @property Collection_Model model
*/
class Collection_Controller extends Controller
{
protected $model = null;
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
Re: phpdoc as code duplication
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.