2

Script API documentation incorrect on member access

Galen

December 26, 2017 16:07

None

Follow

Most of the usable properties in the SceneObjectScript class are actually "protected" and not "public", but the documentation shows them as public. It should updated to reflect that.

Come to think of it, why aren't these properties and most of the methods actually public? I'd like to be able to pass a handle to my SceneObjectScript to other classes and have them use properties and methods on it, but to do so requires me to create lots of delegates and pass handles to methods and private properties into those classes. Here's an ugly example:

new SomeUtilityClass(
    ScenePrivate,
    ObjectPrivate,
    Script,
    Log,
    PostScriptEvent,
    SubscribeToScriptEvent,
    UnsubscribeFromScriptEvent,
    StartCoroutine,
    Wait
);

It's ridiculous and I'm not sure what's gained by having anything in the API be protected, given how scripts work.

13 comments

• 2
  
  Neen December 27, 2017 01:47

  @Gindipple: Why do you bother arguing against him if you're not willing to go all the way and give a proper argument? That's not very helpful. Anyone with a basic understanding of OOP can say "There's multitudes of reasons why you don't want someone to access a member variable directly." but that statement is meaningless on its own.

  And going so far as to say "And I'm not going to give you a specific example, do your own homework." is just pretentious.

  Edited by Neen December 27, 2017 02:01
• 1
  
  Galen December 26, 2017 23:34

  I've done my homework. I'm convinced there isn't a good reason. Hopefully LL will either explain their rationale or otherwise change the access qualifiers.

• 0
  
  Gindipple December 26, 2017 18:57

  "Come to think of it, why aren't these properties and most of the methods actually public?"

  To prevent you from doing things you shouldn't be doing.

   

• 0
  
  Galen December 26, 2017 19:34

  Such as? Tell me what possible thing my own script that I write should not be doing with SceneObjectScript.Log if I pass a reference to "this" from my main script to some other object.

• 0
  
  Gindipple December 26, 2017 19:49

  Private and protected are part of the underlying foundations of OOP. There's multitudes of reasons why you don't want someone to access a member variable directly. You have no idea of its implementation. That's why you are given a defined interface, so that you are forced to access things the way the designer intended.

   

• 0
  
  Andrew Lawrence December 26, 2017 21:59

  ♪♫♪ All I want for Christmas is a script docu wiki, a script docu wiki, a script docu wiki ♪♫♪

• 0
  
  Galen December 26, 2017 22:54

  Gindipple: As usual, you think I'm asking for something because I'm ignorant. Believe it or not, I understand what member access qualifiers are for.

  I'll note that you have yet to give a specific example of how these protected properties (.Log, .Memory, .ObjectPrivate, .ScenePrivate, and .Script) fit the usual explanation for why you would mark a member as protected. I'm assuming that, like me, you haven't found a good reason to.

  Now I'm betting LL just assumed that for the most part, scripters would not write code outside of their SceneObjectScript-derived classes. They probably didn't imagine that someone would define custom classes and pass references into them to that main scene-object class. However, there are plenty of cases I can describe where this is useful.

  Right now, I'm working on creating a next-gen version of Reflex. This time, instead of asking users who will start from my script template to make their own custom Reflex scripts to copy and paste members to the main script class, I'm writing a set of standalone utility classes to manage all the script-to-script communications and more that can be pasted at the end of a script, after the user's custom scene-object script. In the future, these classes will be able to live outside the main script file, so this is good preparation for that time. Naturally, I'd like to pass in a reference to the scene-object class so that the Reflex library can do things like write out log messages, find agents in the scene, start coroutines, post script event messages, and so on. However, since these members of SceneObjectScript are marked as protected, I cannot use the reference to the scene-object object to call those things. Hence the awful workaround of passing in references to each of those pointlessly protected properties (e.g., .ScenePrivate) and methods (e.g., .StartCoroutine() ) that Reflex needs.

  So you're making some vague argument about how sometimes it makes sense to make members private or protected. Yep. So what's the benefit here?

  Edited by Galen December 26, 2017 22:56
• 0
  
  Gindipple December 27, 2017 07:49

  Seriously asking for everything to be made public is just bad.

  They made things the way they are for specific reasons.

  And I did explain why, you just didn't like the answer.

  But I'll state it here again for you.

  You have no idea of its implementation.

  A Logging method might for all you know be a singleton that locks a resource. You need a very specific interface to that. You can't just up and make it public, potentially breaking the underlying structure.

  This is really basic OOP stuff.

  Ask kelly directly, I bet he'd give you some specific reasons. Or smiling, he'll change the code so that you can't do wrong things like he did to me once. Sure I didn't like it, but I get the logic on it. They have to code the system not only to work, but to not let us wrap the rope around our throats too.

  Don't put comments like "As usual..." if you don't want me being defensive.

   

   

• 0
  
  Lex December 27, 2017 08:00

  However to give a rude comparison to SL, as creator i can do horrible things to my "buyers" because i can leave all kinds of openings. I think LL wants to avoid that here, im totally no C# wizard but i guess its not what we script but what a later abuser would write. I trust (and hope) LL have good reasons for it. But asking cant hurt.

• 0
  
  Galen December 27, 2017 12:44

  Gindipple: Look, I don't think you realize how abrasive you can be at times. You had a valid point in arguing that there may be some valid reason why all of those properties and methods are protected and not public. But I already implicitly acknowledged that from the beginning. "Come to think of it, why aren't these properties and most of the methods actually public?" I take for granted that there could be a solid reason for it.

  But that's precisely why I asked. And why I opined that I believed there was no really good reason for it. There is absolutely nothing wrong with speculating and inviting debate.

  So the problem with your string of comments is that you were stating the obvious repeatedly and thus merely badgering me, not contributing constructively. I even gave you an out by asking you to turn your redundant point into a more useful one by giving a hypothetical example; you didn't until your latest begrudging comment.

  There's always a reason for the things you do, of course. But you should take stock of the collective effects of your actions and how they are perceived by others. You're a smart guy, so you have a lot to contribute. But so often your comments come off as pompous, from-the-hip, and personal.

  Probably a lot of mine do, too.

• 0
  
  Galen December 27, 2017 12:50

  Also, I don't want to single Kelly out. Note how I've referred to Linden Lab in this? This is not personal. Kelly is also very smart and quite articulate, I've found. But this is vacation time (Christmas to New Year's Day). Moreover, to some degree, it's not appropriate to always directly message Kelly or anyone at LL when I want to motivate change. Moreover, my main point was about the documentation being incorrect. I don't know if Kelly is even the person to ask about it. In any case, Kelly has actually been very generous in talking with me often about scripting, lately. I don't want to abuse that.

• 0
  
  Galen December 27, 2017 13:29

  To Gindipple's point, I'm not asking for everything to be made public. I was very specific in singling out the protected properties and methods in the SceneObjectScript class. I speculate that they were made thus for what might be regarded as a general best practice: only making public things that people actually need. And while I understand this as a premise, I'm not entirely sympathetic to it. I tend to favor making members public instead of protected (note: not private) unless there is a compelling reason not to.

  For example, the class' default constructor is marked protected. The reason is clear: It's designer did not want users like me overriding its default construction behavior for reasons that should be familiar to OOP programmers. The documentation even alludes to the reason: "Override Sansar.Script.ScriptBase.Init() to initialize the script after properties have been set." If the class allowed you to override the default constructor, you could easily run into cases where you attempt to do things in your script before the script engine is ready for you to. This saves you from yourself.

  Part of why I don't believe there is a solid reason like the hypothetical singleton risk Gindipple considers is that there is uniformity here. All of SceneObjectScript's properties are marked as protected: Log, Memory, ObjectPrivate, ScenePrivate, Script. And every one of these is actually an object instance of a Sansar-proprietary class. However, every one of these objects/classes is available to every script and is meant for "public" consumption. This uniformity among properties suggests to me that this design decision is motivated by a general design practice and not specific safety reasons like with the default constructor.

  At least with the class' methods, I can see that some are public and some are protected. This diversity suggests that there may actually be understandable reasons for not making all of them public. I'd still like to know some of the specific reasons, though, because I can see counter-reasons for making them public, like the ones I've stated prior.

  But generally speaking, the "protected" access qualifier is oriented toward cases where you want to allow someone deriving new classes from your own to be able to use some members but do not want to grant that same access to "outsiders" who are going to use your derived classes. The assumed principle is that you should be protected from yourself. But most often, the intent is that you (a third party) be protected from other people (other third parties) harming you, themselves, or anyone else by using something inappropriate. By analogy, the "do not remove" tags on mattresses are meant for you, the consumer, but the "do not remove" note is for the mattress salesperson, not you.

  But protected status is also often used as a sort of complexity prophylactic. By that I mean that you sometimes use it just as a way to eliminate the clutter of members you don't think your users will need outside of limited contexts. While this clutter minimization is its own virtue, sometimes it gets in the way of maximizing utility. I'm not sure if this is an example of it, but maybe.

  There's more to the general topic of class member access modifiers, but I don't want to discuss every aspect here.

  One thing I will throw into the mix is that problems arise with typical thinking about access modifiers when you step outside the usual assumptions for an "is a" relationship and a "has a" relationship between classes in OOP. Arguably, design patterns in OOP are gradually steering more toward has-a relationships, which is exactly the case I'm dealing with now. That is, I'm making it so your custom scene-object instance "has" an instance of a utility class that wants to manipulate your scene-object instance. In the past I've made it so your custom scene-object "is" an instance of that same utility class. I won't go into detail (unless you really want me to) of why this shift is sometimes valuable, but I think you can see that sometimes it is. And in those cases, one classic problem is that "protected" access discriminates between is-a and has-a OOP relationships. This is the underlying problem which motivated my request for change.

  Edited by Galen December 27, 2017 13:34
• -1
  
  Gindipple December 26, 2017 23:18

  And I'm not going to give you a specific example, do your own homework.

  But if you think it should all be public then by all means see if they will grant your wish. I highly doubt they will because of the simple general reason I pointed out.