On Thu, May 27, 2010 at 12:44 PM, larry@xxxxxxxxxxxxxxxx < larry@xxxxxxxxxxxxxxxx> wrote: > On 5/27/10 11:30 AM, Peter Lind wrote: > > Sure, but @param, @access and possibly @return are but a part. I stand >>>> by my words: document the parent as a stub and provide actual >>>> documentation for the real implementations. Otherwise you're trying to >>>> be *clever* and will see the age-old result: you'll end up shooting >>>> yourself in the foot or worse places. >>>> >>>> Regards >>>> Peter >>>> >>> >>> ... What's "clever" about using OO inheritance the way it's designed to >>> be >>> used? Are you actually suggesting that the solution is to insist on >>> duplicating the docblock in every child class, which is a huge >>> maintenance >>> headache? >>> >> >> If the implementations are the same in all child classes, then you're >> doing OO horribly wrong. >> > > Of course the implementations aren't the same. That would be silly. But > the API is the same, by design. > > > If they're *not* the same, then you'll merely >> be duplicating a part of the documentation (docblocks do *not* just >> consist of @param and @access) while writing the rest of the >> documentation to show what you're actually doing different in each >> method. >> > > I generally do not put a description of the entire internal algorithm into > the docblock, as that is not part of the API. That's also by design. Even > if there is implementation-specific stuff to add, the "short description > line", @params, @return, and lots of other things don't change, nor should > they. So at best you're duplicating half the docblock each time. Still a > high maintenance burden. > > --Larry Garfield > > > -- > PHP General Mailing List (http://www.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > > Larry, I've thought about this very issue before (java developers sometimes lament this issue, too), and I error on the side of duplication if I'm using inheritance. However, I'd say I rarely use inheritance for anything in my development, and I'm much more likely to use composition. When a project evolves that's built almost entirely using design patterns focused on composition, I find that I very rarely have to duplicate any documentation, or rework documentation later on because a completely new component is being used. Outside of PHP (Scala, Objective C, F#, etc.), it seems like inheritance is advocated much less frequently, due to the power and simplicity of composition (e.g., change behavior at runtime, requires less knowledge of the parent classes.) Quoting the Head First book on design patterns: "Favor composition over inheritance" Now, there are situations where either inheritance is the most appropriate, and/or the architecture is not directly under your control. And, as I said at the beginning, I tend to error on the side of duplication. I just try to never put myself in that situation :) Adam -- Nephtali: PHP web framework that functions beautifully http://nephtaliproject.com
