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

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: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.
I use them in order to tell Netbeans what types/classes these are so I can e.g. "jump" to class declarations. I don't use them as comments.

Like this: http://www.mybelovedphp.com/2009/01/27/ ... gniter-ii/
There are 10 types of people in this world, those who understand binary and those who don't
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 »

Function/method names tell you rarely, how to use them or what you should remember about, i.e. whether they have side effects or not. I can imagine names like findActivePageForRequest() which are self-descriptive and tell what they do, but findActivePageForRequestWithSideEffectsModiyfingTheActivePageSettingsInTheClassMethodReliesOnXYZSettings() ? My point is that sometimes just a description "what the function/method does" is not enough, because there are many more aspects that could be, and in some cases - they even should be described that cannot be easily encoded in the function name. Otherwise, there would be absolutely no need to write manuals, but for some reason people do write them and use.
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 »

Zyxist wrote:Function/method names tell you rarely, how to use them or what you should remember about, i.e. whether they have side effects or not. I can imagine names like findActivePageForRequest() which are self-descriptive and tell what they do, but findActivePageForRequestWithSideEffectsModiyfingTheActivePageSettingsInTheClassMethodReliesOnXYZSettings() ? My point is that sometimes just a description "what the function/method does" is not enough, because there are many more aspects that could be, and in some cases - they even should be described that cannot be easily encoded in the function name. Otherwise, there would be absolutely no need to write manuals, but for some reason people do write them and use.
That second method you mention is a poorly developed method/class. It does more than one thing. If a class/method has a dependency then that dependency should be in the constructor, and should raise an exception when that dependency is not met (so your test will catch this).
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 »

VladSun wrote:

Code: Select all

	/**
	 * @param  string|array $msg
	 * @return bool
	 */
That breaks code completion in most IDEs, the mixed parameter/return type does not work with NuSphere's code completion at least. Also my IDE already solves the problem of showing the available methods on each class (someone mentioned that as a reason for writing comments a few posts back).

I agree with you guys its nice to have the IDE popups, but I also agree with Jenk, the popups are more than informative without any superfluous comments, in a good code base. For example if you're on a class called 'vehicle finder', and calling a method w/ the signature 'listByTitles(array $titles)' - its not hard to guess what it does. And if you can't guess, there should be a unit test, showing what inputs you can use, which inputs you cannot, relationships between those inputs and possible outputs, etc.. (which would be too much info for a comment)
Zyxist wrote: there would be absolutely no need to write manuals, but for some reason people do write them and use.
There's a difference between a 'reference guide' and an 'api doc'. An API Doc restates a method's signature. Here's one from Zend:

Code: Select all

/**
     * Render WHERE clause
     *
     * @param string   $sql SQL query
     * @return string
     */
    protected function _renderWhere($sql)
USELESS! I didn't have to hunt to find this example. This is the norm.

Here's another:

Code: Select all

/**
     * Adds a WHERE condition to the query by AND.
     *
     * If a value is passed as the second param, it will be quoted
     * and replaced into the condition wherever a question-mark
     * appears. Array values are quoted and comma-separated.
     *
     * <code>
     * // simplest but non-secure
     * $select->where("id = $id");
     *
     * // secure (ID is quoted but matched anyway)
     * $select->where('id = ?', $id);
     *
     * // alternatively, with named binding
     * $select->where('id = :id');
     * </code>
     *
     * Note that it is more correct to use named bindings in your
     * queries for values other than strings. When you use named
     * bindings, don't forget to pass the values when actually
     * making a query:
     *
     * <code>
     * $db->fetchAll($select, array('id' => 5));
     * </code>
     *
     * @param string   $cond  The WHERE condition.
     * @param string   $value OPTIONAL A single value to quote into the condition.
     * @param constant $type  OPTIONAL The type of the given value
     * @return Zend_Db_Select This Zend_Db_Select object.
     */
    public function where($cond, $value = null, $type = null)
This one is 'too useful'... Name bindings?

Actually I was double checking and the ONLY place they documented this was this comment. That's bad in my opinion, it should really be here: http://framework.zend.com/manual/en/zend.db.select.html

So in effect they now have multiple documentation guides. People that read one and not the other learn half the code, and of course both have to be kept up to date! I never use name bindings, because completion doesn't work (Db adapter ->select() returns a PDOObject|Zend_Db_Select, my IDE doesn't handle multiple return types in docblocks, so I get no popup description of that method). I knew they existed but never remembered reading about them in the documentation, thats because its entirely undocumented effectively hidden from code complete as well.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Re: phpdoc as code duplication

Post by Weirdan »

josh wrote: I agree with you guys its nice to have the IDE popups, but I also agree with Jenk, the popups are more than informative without any superfluous comments, in a good code base.
Uhm, would your IDE show class methods for 'fluent interface'-style calls if code base is not annotated with @return's? Consider the following

Code: Select all

interface Duck {
  public function walk();
  public function quack();
}

class A implements Duck {
   public function walk() { return 'A walks'; }
   public function quack() { return 'A quacks'; }
}

class B implements Duck {
  public function walk() { return 'B walks'; }
  public function quack() { return 'B quacks'; }
}

/**
 * @return Duck
 */
function makeDuck() {
  if (1 == rand(1,2)) {
     return new A;
  } else {
     return new B;
  }
}
makeDuck()->quack();
- if makeDuck() had no @return annotation would PHPEd realize it returns Duck?
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 »

No it would not realize that without a php doc. I guess for me its easier to type quack() then it is to type /** @return Duck */ each time. If I call a method wrong I know within seconds anyways (tests). I mean that's not why I write tests, to avoid commenting code. Its just that tests have so many benefits it changes how you program.

The whole point of dynamic languages is you don't know the return type. Bulletproof code completion is simply a pipe dream I don't chase in PHP anymore.

If its something easy like one @return per method on a particular class I'll sometimes put the docblock, but thats only if lack of code completion actually surfaces as a problem.
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 »

Weirdan wrote:
josh wrote: I agree with you guys its nice to have the IDE popups, but I also agree with Jenk, the popups are more than informative without any superfluous comments, in a good code base.
Uhm, would your IDE show class methods for 'fluent interface'-style calls if code base is not annotated with @return's? Consider the following

Code: Select all

interface Duck {
  public function walk();
  public function quack();
}

class A implements Duck {
   public function walk() { return 'A walks'; }
   public function quack() { return 'A quacks'; }
}

class B implements Duck {
  public function walk() { return 'B walks'; }
  public function quack() { return 'B quacks'; }
}

/**
 * @return Duck
 */
function makeDuck() {
  if (1 == rand(1,2)) {
     return new A;
  } else {
     return new B;
  }
}
makeDuck()->quack();
- if makeDuck() had no @return annotation would PHPEd realize it returns Duck?
That point I've been making is a method named "makeDuck" already tells me it's going to make a duck...
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 »

You're talking about obvious documentation, which is indeed superfluous, but often I have methods which take an array of parameters - like list functions that can have multiple filtering / sorting criteria. So I explain the possible values that can be sent in the parameters in the doc block above the function
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 »

For me the reason I use phpdoc san be summarized in one sentence - PHP is not a strict typed language and I need type hinting ;)...
There are 10 types of people in this world, those who understand binary and those who don't
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 »

Well I agree that a docblock is better than no form of documentation. I just disagree that you should have docblock documentation, unit test documentation, and 'reference guide' documentation. Too disparate
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 »

I don't know how Jenk realized from the method name whether I injected dependencies through a constructor or not, but my post was related to completely different things. I just said that requiring that "the function/method name must always precise, what it does" and "unit tests are a documentation" are a bit nonsense in some cases, not whether phpdoc comments in projects like ZF are meaningful. This idea works only if the other programmers already know the terminology we are going to use, and everything is done in the most standard way using conventions that apply everywhere. But some people write more complex projects. Here, even the most descriptive name can be useless: computeAmbiguityIndex(). Fine, I know that the method computes some "ambiguity index", but I don't know what this ambiguity index is, why I do or why I do not need it, where it is applied. And if developers do not want to describe the internal structure details in Programmer's Reference, they should at least do it in phpdoc. And not by repeating the method name, like Zend guys do (it is annoying me, too).

When it comes to unit tests, there are many misconceptions about them. Many people believe that 100% test coverage means a bug-free code and some others believe it is a complete documentation. Unit tests are written for machines, so that they can verify the correctness of the implementation (but not the quality of the idea behind it). We can generate a form of documentation for them, but it will not be completed for the same reason, as in case of method names, and analyzing the code of unit tests in order to get to know, what it does is a nonsense. I don't have a time for it. I'm a human, a single English sentence is much more expressive for me, than 200 lines of test code.

Last of all, it's quite interesting that all of you say phpdoc comments are generally bad, but my practice shows that programmers generally want them. The first versions of one of my libraries did not have them at all, because I wanted to develop a separate reference guide, and I was widely criticized for not using them. I registered the project on Ohloh, and it started claiming: "Oops! Extremely few source code comments" which was a signal: "It does not matter that you have a 0,5 MB of documentation in a text form. If you do not start using phpdoc comments, we will consider your project as poorly-designed". Maybe this is a good explaination why developers use these comments.
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 »

Zyxist wrote: Here, even the most descriptive name can be useless: computeAmbiguityIndex(). Fine, I know that the method computes some "ambiguity index", but I don't know what this ambiguity index is, why I do or why I do not need it, where it is applied. And if developers do not want to describe the internal structure details in Programmer's Reference
Right, but what I was arguing was that the programmer's reference is a better place for that. I don't need to learn what an ambiguity index is each time I maintain that method. Only once, or very rarely would I need to revisit that documentation. The name compute ambiguity index is dead simple, if I know what an ambiguity index is, I shouldn't need anything else.
others believe it is a complete documentation. Unit tests are written for machines, it will not be completed
Wrong, they are written for humans (and one of their properties is a machine can execute them). They can document just as well if not better than a phpdoc block ;-) Its just a matter of writing good assertion messages, which are English sentences mind you.

With a unit test you are showing what kind of output you are getting for each input. On the other hand, that is different from a docblock which shows all possible inputs & output types, but not their values or how they are related (without writing additional prose, which is basically the same thing as a unit test but not self verifying, and now you have documentation & code in the same file. We don't put business logic & code in the same file, why put documentation & code in the same file?)
I don't have a time for it. I'm a human, a single English sentence is much more expressive for me, than 200 lines of test code.
Each English sentence or 'specification' corresponds to about 2 lines of test code. Several empirical studies done by corporations such as Microsoft have shown that unit tests very rarely add to the amount of time it takes, but may subtract.
I registered the project on Ohloh, and it started claiming: "Oops! Extremely few source code comments" which was a signal: "It does not matter that you have a 0,5 MB of documentation in a text form. If you do not start using phpdoc comments, we will consider your project as poorly-designed". Maybe this is a good explaination why developers use these comments.
I don't think a comment you got on Ohloh necessarily reflects what best practice is, but I guess I would agree with you that most people haven't even heard of unit testing. I think most people would agree having tests is a good thing, but hardly do projects get criticized for not having them. So clearly you can't define best practice this way. I agree writing a docblock is a better political action to take. However not writing tests could get you impeached :lol:
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 »

Sorry to keep reviving this but 2 other things I noticed:

- When using design patterns like 'wrapper', docblocks are not seen by my IDE (In PHP I implement wrappers using __call)
- If you type @return Zend_Db_Select, but I am using an extended version of Zend_Db_Select, I get no completion (Ex. one() lives on base class, two() lives on extended class. After typing one()-> you will not get two() as a code completion option, nor will it give you docblock documentation.)

So if docblocks are needed for 'complex' projects, I don't see how you work around these pervasive issues. Docblocks do not work with design patterns, or fluent interfaces. The only 'work around' I see is to use easy to remember names, which you should already be doing ;-)

Also with multiple return types, your IDE will generally show the methods from neither, or worse yet will show methods that may or may not be available under all conditions (only testing could verify that you're calling methods that exist in all circumstances)
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 »

There are 10 types of people in this world, those who understand binary and those who don't
koen.h
Forum Contributor
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: phpdoc as code duplication

Post by koen.h »

from http://www.framework.zend.com/manual/en ... style.html
Every function, including object methods, must have a docblock that contains at a minimum:

* A description of the function
* All of the arguments
* All of the possible return values

It is not necessary to use the "@access" tag because the access level is already known from the "public", "private", or "protected" modifier used to declare the function.
What they say is that @access is duplication. Note that the description of the function should be clear by its name. It's arguments are known from the declaration of the function, and it's return values will hopefully known from the declaration someday.

While I'm not a proponent of docblocks, I've decided that I am going to use them in my public projects. Leaving them out seems to convince many people that the project is probably not that professional. Another reason is that return types still are not supported in PHP. A third reason is that there are cases where I've struggled to find a good intention-revealing method name (this may be a code smell, also a lack of English proficiency smell). Or sometimes the best intention-revealing name would be rather silly in a public API (eg findParentsCategoriesIncludingRecursiveTheParentsOfParents).
Post Reply