Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

Re^3: Simple question about Inside-Out objects

by Herkum (Parson)
on Mar 13, 2007 at 20:20 UTC ( #604676=note: print w/replies, xml ) Need Help??

in reply to Re^2: Simple question about Inside-Out objects
in thread Simple question about Inside-Out objects

I have looked at both of them and the reason that I don't use them is the same reason that I don't use a lot of other 'good' modules, poor documentation.

While I understand that Class::Std is not the perfect for solving all the problems for InsideOut objects. The concepts well explained and the documentation is easier to understand. That is why I recommended it to blazar

  • Comment on Re^3: Simple question about Inside-Out objects

Replies are listed 'Best First'.
Re^4: Simple question about Inside-Out objects
by xdg (Monsignor) on Mar 13, 2007 at 22:11 UTC
    the reason that I don't use them is the same reason that I don't use a lot of other 'good' modules, poor documentation

    I'd welcome any constructive feedback on the documentation of Class::InsideOut. I've tried hard to make that documentation simple for those who just want it to work and keep separate the theoretical underpinnings and complexities. I'm sorry that you didn't find it to be helpful and would like to hear your thoughts on what would make it more useful to you.

    I can be reached via dagolden at cpan dot org.


    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

      Very mature response to an otherwise insulting response. ++you.

      The problem I have with any documentation is the case when I am presented with an example, but I have no knowledge of why I would need to understand that example, let alone if that example is even relevant to my needs. While I fully realize that the author can in no way be held responsible for being able to explain module usage to 100% of their readers -- you have to ask yourself at all times ... does this example make sense by itself?

      And yes, it's OK if it doesn't.

      But what if you can make it easier to understand anyways? What if you could write examples that progressively build up to them first. That is, don't introduce new concepts in the code snippet ... explain what the purpose is first. Here, take this quote from your docs:
      Additional functions may be imported as usual by including them as arguments to use. For example:
      use Class::InsideOut qw( register public ); public name => my %name; sub new { register( shift ) }
      OK ... so I see that I can import functions into my class. But what do register and public mean? You say "that is not important right now, I will explain those later." Except you are not here to tell me that. Instead I now stop, and waste brain cells wondering when and why I would need to alter my constructor to use register.

      Instead, I would have only used one line:

      use Class::InsideOut qw( register public );
      Don't show the usage for register and public until it is time to talk about them.

      Another point -- your module seems to imply that the user needs to learn a new language subset, for example:
      public name => my %name; readonly ssn => my %ssn; private age => my %age; $name{ refaddr $self } = "James"; $ssn { id $self } = 123456789; $age { id $self } = 32;
      Instead of throwing these cryptic and seemingly unusable code snippets at the learner, maybe you should instead teach them the language first? "Hey?!? How come I don't gotta stick a comma between readonly and ssn?" :/

      While I do not agree with Herkum's tact, I must confess that the docs are a bit daunting. I must also confess that I am not a supporter of Inside Out Objects, and have not bothered to read Damian's writings on them. If I had, perhaps your docs would seem more intuitive to me, but if your ulterior motive is to attract users -- you gotta dumb it down sell it man. :)

        I am sorry, I did not mean to come off as insulting, and your post was very well written, I wish I had put the time into it that you did.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://604676]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (7)
As of 2018-06-22 05:55 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (121 votes). Check out past polls.