[Catalyst] Why does $c->stats require -Debug flag?

[Jon Schutz]

On Mon, 2008-04-21 at 19:18 +0100, Matt S Trout wrote:
> On Mon, Apr 21, 2008 at 11:29:56AM +0930, Jon Schutz wrote:
> > I'm making a stand here for the rights of all developers!  Backward
> > compatibility is a must for defined interfaces, but to carry that
> > through to say that all design decisions turn into interfaces that must
> > be preserved, even though not meant for external consumption,
> > discourages innovation.  Many factors separate good projects from bad,
> > and one is well defined interfaces!
> 
> And the tradition in perl is that if it doesn't start with an _, it's a
> public interface.

The leading underscore indicates a private variable or function, from
which it does _not_ follow that everything else is public.

Example - Catalyst.pm contains:

1. Clearly private, internal methods with leading underscore and
documentation in comments

2. Private methods with leading underscore that do pop up in the perldoc
($c->_localize_fields, which I presume is probably just an oversight)

3. Perldoc-documented methods with no leading underscore that are
identified as internal methods (like 'friend' or 'protected' methods, I
guess) - the doc says "These methods are not meant to be used by end
users".

4. Perldoc-documented methods with no leading underscore that are bona-
fide user API methods.

5. Undocumented methods with no leading underscore ($c->setup_finished,
for example).

The point is, it's pretty clear what users _are_ allowed to access, so
anyone applying the leading underscore rule does so at their peril.

> 
> DBIx::Class originally used an "if it's not documented it's not a public
> interface" approach and I got massive negative feedback over that from
> people who'd followed the perl convention and got bitten later.
> 

But presumably that was because there was insufficient documentation in
the first place, so early adopters had to get into the code.

Which leads me to an aside - Why do we insist on having unit tests but
let basic API documentation escape?  How can we write tests without the
API documentation??  

Really, we are only having this discussion because $c->stats had no docs
in the first place.  Fact is I agree with most of what you say, it's
just a question of where the boundary lies.

> If I had a choice, I'd follow "documentation means public, no docs means
> use at your own risk". But there's an established standard, and that isn't
> it, so we live with the world we have.

> You're not making a stand for anything except your right to buck standard
> perl practice and get away with it; I tried, failed, had unhappy users, and
> learned. Welcome to the real world sucking. If it was perfect, we'd need a
> lot less developers :)
> 

Not at all; the implication of what you say is that "standard perl
practice" is poor software engineering practice (not to say that there
aren't inadequacies, of course there are).  Respecting APIs is pretty
fundamental, yes?

-- 

Jon Schutz                        My tech notes http://notes.jschutz.net
Chief Technology Officer                        http://www.youramigo.com
YourAmigo