Re: Method documentation

On 27 May 2010 18:10, Adam Richardson <simpleshot@gmail.com> wrote: > On Thu, May 27, 2010 at 12:44 PM, larry@garfieldtech.com < > larry@garfieldtech.com> 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 > With the up-and-coming traits facility for PHP, it will be interesting on how this gets resolved for documentation readers. -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling