Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

Re^5: Simple question about Inside-Out objects

by Anonymous Monk
on Mar 13, 2007 at 22:54 UTC ( #604706=note: print w/ replies, xml ) Need Help??


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

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. :)


Comment on Re^5: Simple question about Inside-Out objects
Select or Download Code
Re^6: Simple question about Inside-Out objects
by Herkum (Parson) on Mar 14, 2007 at 00:53 UTC

    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?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://604706]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (11)
As of 2014-09-03 07:31 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite cookbook is:










    Results (35 votes), past polls