Terminology / naming convention questions

[Milan Zimmermann]

I have also a few terminology / naming convention questions: 

1. Definition or declaration? 

If we see slots in a factory constructor such as

  class MyClass myFactory: arg = (

  |

    something = arg something. 

    somethingElse

  |)

Do we say we are 'defining a slot' "something" and 'declaring a slot' "somethingElse"?

2. Similarly, if the |..| section is in an instance method on MyClass defined as

   "myInstanceMethod: arg = (|..|)"

Do we say we are 'defining a local variable' "something" and 'declaring a local variable' "somethingElse"?

Is the above terminology acceptable, reasonable, not reasonable, wrong? If the latter, what terminology should  be used instead?

3. visibility naming conventions: if we write "public class MyClass myFactory: arg = (|..|)", do we say the 'class MyClass is public' or 'the factory constructor of MyClass is public'? I think the latter, as there is no 'class visibility' - everything is a message send, so there is only 'method or constructor visibility' -  but wanted to check .

Thanks

Milan

[Gilad Bracha]

On Sat, Aug 7, 2021 at 11:30 PM Milan Zimmermann <milan.zi...@gmail.com> wrote:

I have also a few terminology / naming convention questions: 

1. Definition or declaration? 

If we see slots in a factory constructor such as

  class MyClass myFactory: arg = (

  |

    something = arg something. 

    somethingElse

  |)

Do we say we are 'defining a slot' "something" and 'declaring a slot' "somethingElse"?

This is very sensible, but not the scheme I adopted in the spec. Generally, we speak of declarations. Definitions have a technical meaning for top level classes: we distinguish module declaration (top level class source), module definition

(class object of top  level class) and module (instance of top level class).  See spec, section 6.4. Also see 3.5 which discusses methods and what defines them (mixins) as opposed to their declarations (again, essentially source).

2. Similarly, if the |..| section is in an instance method on MyClass defined as

   "myInstanceMethod: arg = (|..|)"

Do we say we are 'defining a local variable' "something" and 'declaring a local variable' "somethingElse"?

See above.

Is the above terminology acceptable, reasonable, not reasonable, wrong? If the latter, what terminology should  be used instead?

Very reasonable.

3. visibility naming conventions: if we write "public class MyClass myFactory: arg = (|..|)", do we say the 'class MyClass is public' or 'the factory constructor of MyClass is public'? I think the latter, as there is no 'class visibility' - everything is a message send, so there is only 'method or constructor visibility' -  but wanted to check .

I think there is a bit of a misunderstanding here. The modifier indeed applies to a method - but to the factory method.   The access modifier applies to the class accessor -  a hidden method that returns the class object.

In my previous email about access control, I said that the modifier applies to classes - but technically that is imprecise as you say.  In practice, the class accessor method is an implementation artifact and you cannot detect it in the language, even via reflection, so the imprecision is harmless.

--

Cheers, Gilad

[Milan Zimmermann]

Hi Gilad,

Originally I was not sure I should be asking terminology questions but now I am glad I did.  I think I am discovering too much I am unclear on, and feel I should not constantly take your time and do more homework by myself instead..

Having said that, let me continue for one more round here but I will slow down after.

On terminology: It was not my intention to invent any new terminology, but rather understand and use the established one, which after your comments I feel understand better now, and will start using it. I will comment on that inline

Questions (from the access modifier post and this post) I am pulling up here:

Question 1 context:

Hmm, despite my best intentions not to, after I realized there is some misunderstanding on my end around 'factory' - you also noticed that - I opened the specs, and got myself in trouble :) There is a sentence like this that maybe shows my deep misunderstanding, so before I continue: The sentence is like this:

Ch 2.3 version 0.101: "Class declarations create a class factory object that provides the means of producing instances of the class. The factory object supports at least one message that produces new instances. This is known as the primary factory method. By default, it is called new. "

So question 1 (with many follow up questions):

----

Does the specs sentence mean that, if I were to look in memory, given a class C I could see: 

1) one object for class C. 

2) one 'factory object'? This 'factory object' has at least one method (called 'primary factory method')? This 'factory object' produces instances of class C (items in 3))

3) one or more instance objects of class C - well this is the only thing I am sure about, so no question here  :) 

If it is correct, I have throughout the years, missed the existence of the 'factory object' - although it may be intentionally hidden, I feel like it's existence clarifies a lot .. would this 'factory object' be the object hosting the 'primary factory constructor' and also all 'static' methods (those in the third set of bracket)? ... If it is not correct, I will get back to thinking :)

So assuming such 'factory object' indeed exists, as I understand from the specs sentence:

- If I see written somewhere just the term 'factory' alone (as I am sure is used on occasions) - does that refer to the 'factory object' or to the 'primary factory method'? I think now the former (but need to ask)

- I should not be using the term 'constructor', as in 'primary factory constructor' (as I was), but instead, the term 'primary factory method' for the method on the first line of the class source, and 'factory method' for any (static) method in the 3rd set of brackets of class source, is that correct?

Question 2) From previous email

----

| mz>> I see most (all?) constructors on top level classes in the IDE are not public.

|| gb>> No. Top level classes don't have an explicit access modifier, ever, but primary factories are always public. 

|| gb>> The modifier on a class dictates the classes' accessibility, not the factory method's.

|| gb>> Hence it makes no sense for top  level classes - they are not members of any other object. Once you have access to a class, you can instantiate it (hence factory is always public).

I am trying to understand clearly (well, maybe I am trying not to understand fully, but create some rules for myself):

a) On a top level class: placing accesss modifier (private, public) on top level class' primary factory method (the first line of class source) is irrelevant - the access modifier will be ignored, is that right?

b) Can I 'imagine', purely as a thinking help, the primary factory method on a top level class always have 'public' access modifier on it?  Anything wrong with such helper?

c) Given a top level class Top1 which code starts like this: "MOD class Top1 usingPlatform: platform = (..)(..)": Is it correct that any top level class Top2 can pull Top1 on it's slot, irrespective of access modier on Top1 primary factory method on the first line (even if MOD=private), for example like this:

top level class source: Top2 usingPlatform: platform andTop1: T1 = (|Top1_slot = T1|)

instantiation of Top2, e.g. in Workspace:  Top2 usingPlatform: platform andTop1: Top1.

Ok, so having asked two questions, which have about ten more questions in them, just follow up notes inline

On Sunday, 8 August 2021 at 08:10:07 UTC-7 Gilad Bracha wrote:

On Sat, Aug 7, 2021 at 11:30 PM Milan Zimmermann <milan.zi...@gmail.com> wrote:

I have also a few terminology / naming convention questions: 

1. Definition or declaration? 

If we see slots in a factory constructor such as

  class MyClass myFactory: arg = (

  |

    something = arg something. 

    somethingElse

  |)

Do we say we are 'defining a slot' "something" and 'declaring a slot' "somethingElse"?

This is very sensible, but not the scheme I adopted in the spec. Generally, we speak of declarations. Definitions have a technical meaning for top level classes: we distinguish module declaration (top level class source), module definition

(class object of top  level class) and module (instance of top level class). 

Ah this definitely clarifies things for me, a lot. I have struggled with terminology, and will have to change it in all notes I produced. So a summary for myself, hope this now matches the terms used:

Module Declaration: Source of top level class

Module Definition: class object of top level class

Module:   instance of top level class (this one I was clear on)

Slot declaration: expression between | | in primary factory method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Variable declaration: expression between | | in instance method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

 

See spec, section 6.4. Also see 3.5 which discusses methods and what defines them (mixins) as opposed to their declarations (again, essentially source).

Will do.  

2. Similarly, if the |..| section is in an instance method on MyClass defined as

   "myInstanceMethod: arg = (|..|)"

Do we say we are 'defining a local variable' "something" and 'declaring a local variable' "somethingElse"?

See above.

Yes.  

Is the above terminology acceptable, reasonable, not reasonable, wrong? If the latter, what terminology should  be used instead?

Very reasonable.

Cool, thanks. But I will use the terms currently used, as summarized above; I did not intend to invent new terms, but was not clear on the currently used terms. 

3. visibility naming conventions: if we write "public class MyClass myFactory: arg = (|..|)", do we say the 'class MyClass is public' or 'the factory constructor of MyClass is public'? I think the latter, as there is no 'class visibility' - everything is a message send, so there is only 'method or constructor visibility' -  but wanted to check .

I think there is a bit of a misunderstanding here. The modifier indeed applies to a method - but to the factory method.   The access modifier applies to the class accessor -  a hidden method that returns the class object.

In my previous email about access control, I said that the modifier applies to classes - but technically that is imprecise as you say.  In practice, the class accessor method is an implementation artifact and you cannot detect it in the language, even via reflection, so the imprecision is harmless.

So I think part of my question was confusing when I spoke of 'class visibility', I actually meant 'object visibility' which should have been 'object accessibility'. The 'class accessor' you are mentioning here is another thing I am not aware of - good to be aware even if it is implementation. 

I am satisfied with this until I read the document you sent in the other thread.

 If I still feel misunderstandings I will ask about it later. As I mentioned, I need to do more homework.

Thanks 

Milan

--

Cheers, Gilad

[Gilad Bracha]

On Sun, Aug 8, 2021 at 11:23 PM Milan Zimmermann <milan.zi...@gmail.com> wrote:

Question 1 context:

Hmm, despite my best intentions not to, after I realized there is some misunderstanding on my end around 'factory' - you also noticed that - I opened the specs, and got myself in trouble :) There is a sentence like this that maybe shows my deep misunderstanding, so before I continue: The sentence is like this:

Ch 2.3 version 0.101: "Class declarations create a class factory object that provides the means of producing instances of the class. The factory object supports at least one message that produces new instances. This is known as the primary factory method. By default, it is called new. "

So question 1 (with many follow up questions):

----

Does the specs sentence mean that, if I were to look in memory, given a class C I could see: 

1) one object for class C. 

If you could look in physical memory, maybe, depending  on the implementation. You should however know or care unless you are implementing such a system.

2) one 'factory object'? This 'factory object' has at least one method (called 'primary factory method')? This 'factory object' produces instances of class C (items in 3))

Yes, you'll always have one of those.

3) one or more instance objects of class C - well this is the only thing I am sure about, so no question here  :) 

Yes.

Let me elaborate (sorry, I fear the spec has confused you further).  The term class factory object is used to distinguish it from the class itself, but that is a distinction for the implementor, not the user. In an implementation, there is likely a representation of the class, that probably points to a mixin and a superclass, and may or may not have other things. This is distinct from the user accessible object that represents the class in the language, which we often refer to informally as the class, or the class object, or the class factory object (all names for the same thing). 

If it is correct, I have throughout the years, missed the existence of the 'factory object' - although it may be intentionally hidden, I feel like it's existence clarifies a lot .. would this 'factory object' be the object hosting the 'primary factory constructor' and also all 'static' methods (those in the third set of bracket)?

Yes, but it is the same as what you thought of a the class object all along.

... If it is not correct, I will get back to thinking :)

So assuming such 'factory object' indeed exists, as I understand from the specs sentence:

- If I see written somewhere just the term 'factory' alone (as I am sure is used on occasions) - does that refer to the 'factory object' or to the 'primary factory method'? I think now the former (but need to ask)

I won't swear to anything, it depends on context.

- I should not be using the term 'constructor', as in 'primary factory constructor' (as I was), but instead, the term 'primary factory method' for the method on the first line of the class source, and 'factory method' for any (static) method in the 3rd set of brackets of class source, is that correct?

Yes. Constructor reeks of Java/C++ etc. I may occasionally use it as a device to communicate with programmers from those communities, but in Newspeak itself we don't have such a thing.

Question 2) From previous email

----

| mz>> I see most (all?) constructors on top level classes in the IDE are not public.

|| gb>> No. Top level classes don't have an explicit access modifier, ever, but primary factories are always public. 

|| gb>> The modifier on a class dictates the classes' accessibility, not the factory method's.

|| gb>> Hence it makes no sense for top  level classes - they are not members of any other object. Once you have access to a class, you can instantiate it (hence factory is always public).

I am trying to understand clearly (well, maybe I am trying not to understand fully, but create some rules for myself):

a) On a top level class: placing accesss modifier (private, public) on top level class' primary factory method (the first line of class source) is irrelevant - the access modifier will be ignored, is that right?

Apparently. It really should be a syntax error, but I just checked and it is ignored.

b) Can I 'imagine', purely as a thinking help, the primary factory method on a top level class always have 'public' access modifier on it?  Anything wrong with such helper?

This idea of having access modifiers on  top level classes is getting out of hand. They are meaningless and illegal, and if the system accepts them it is a bug. It can only lead to confusion.

Remember, the modifier is for the class accessor, not for the factory method. The class accessor only exists in the enclosing class.  A top level class, by definition, has no enclosing class, and therefore no accessor, and thus no access modifier.

c) Given a top level class Top1 which code starts like this: "MOD class Top1 usingPlatform: platform = (..)(..)": Is it correct that any top level class Top2 can pull Top1 on it's slot, irrespective of access modier on Top1 primary factory method on the first line (even if MOD=private), for example like this:

top level class source: Top2 usingPlatform: platform andTop1: T1 = (|Top1_slot = T1|)

instantiation of Top2, e.g. in Workspace:  Top2 usingPlatform: platform andTop1: Top1.

See above.  The usage in the workspace has nothing to do with access modifiers. The classes Top1 and Top2 are accessible because they are in the IDE's root namespace, which the workspace can access because it's doesNotUnderstand: method consults that namespace. The method #usingPlatform:andTop1: is accessible because it is a primary factory method, which is always public.

Slot declaration: expression between | | in primary factory method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Variable declaration: expression between | | in instance method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

If I was very picky,  I'd say that we have instance slots and local slots.  But this fine.

--

Cheers, Gilad

[Milan Zimmermann]

Gilad,

Thanks again for your detail (and patient) comments. 

I read them earlier this evening and re-read now, and feel no need for more questions. I  am writing follow up comments inline but there are no questions there.

The terminology that you helped with, will help me to orient myself in the specs and documents better. 

Your follow up around the 'class factory object' put me back on safer grounds. Same with your comments on the  'class accessor'.

I do plan to summarize this into a (not too long this time) 'summary document' chapters on terminology and accessibility, but only this weekend or later, once I also find time to go over the accessibility (and more) PDF. I will also review what I wrote so far online, and correct terminology and things that I feel I understand better now (just don't want to leave things online that would be too off).

On Monday, 9 August 2021 at 15:58:17 UTC-7 Gilad Bracha wrote:

On Sun, Aug 8, 2021 at 11:23 PM Milan Zimmermann <milan.zi...@gmail.com> wrote:

1) one object for class C. 

If you could look in physical memory, maybe, depending  on the implementation. You should however know or care unless you are implementing such a system.

Ok.  

2) one 'factory object'? This 'factory object' has at least one method (called 'primary factory method')? This 'factory object' produces instances of class C (items in 3))

Yes, you'll always have one of those.

3) one or more instance objects of class C - well this is the only thing I am sure about, so no question here  :) 

Yes.

Let me elaborate (sorry, I fear the spec has confused you further).  The term class factory object is used to distinguish it from the class itself, but that is a distinction for the implementor, not the user.

In an implementation, there is likely a representation of the class, that probably points to a mixin and a superclass, and may or may not have other things.

This is distinct from the user accessible object that represents the class in the language, which we often refer to informally as the class, or the class object, or the class factory object (all names for the same thing). 

This paragraph definitely placed me back to safety.  I read too much into the term 'class factory object' in the sentence, got confused and tried to get my way to understand something that is not.

That also hopefully justifies my reasons to keep asking for terminology help, when I am not sure what terms refer to, or overlaping terms are used, I get in trouble. 

 

If it is correct, I have throughout the years, missed the existence of the 'factory object' - although it may be intentionally hidden, I feel like it's existence clarifies a lot .. would this 'factory object' be the object hosting the 'primary factory constructor' and also all 'static' methods (those in the third set of bracket)?

Yes, but it is the same as what you thought of a the class object all along.

Right, as you explained above, for the language user: class ~ class object ~ class factory object.

 

- If I see written somewhere just the term 'factory' alone (as I am sure is used on occasions) - does that refer to the 'factory object' or to the 'primary factory method'? I think now the former (but need to ask)

I won't swear to anything, it depends on context.

Ok that is fair. After clearing some confusion above, it feels like now will be much easier to understand what was meant.

 

- I should not be using the term 'constructor', as in 'primary factory constructor' (as I was), but instead, the term 'primary factory method' for the method on the first line of the class source, and 'factory method' for any (static) method in the 3rd set of brackets of class source, is that correct?

Yes. Constructor reeks of Java/C++ etc. I may occasionally use it as a device to communicate with programmers from those communities, but in Newspeak itself we don't have such a thing.

Ok, that is good to be confirmed.  I will remove / fix references to 'constructor'  in things I wrote.

Question 2) From previous email

----

| mz>> I see most (all?) constructors on top level classes in the IDE are not public.

|| gb>> No. Top level classes don't have an explicit access modifier, ever, but primary factories are always public. 

|| gb>> The modifier on a class dictates the classes' accessibility, not the factory method's.

|| gb>> Hence it makes no sense for top  level classes - they are not members of any other object. Once you have access to a class, you can instantiate it (hence factory is always public).

I am trying to understand clearly (well, maybe I am trying not to understand fully, but create some rules for myself):

a) On a top level class: placing accesss modifier (private, public) on top level class' primary factory method (the first line of class source) is irrelevant - the access modifier will be ignored, is that right?

Apparently. It really should be a syntax error, but I just checked and it is ignored.

Yeah, I tried 'primary' on top level calss and it worked.

 

b) Can I 'imagine', purely as a thinking help, the primary factory method on a top level class always have 'public' access modifier on it?  Anything wrong with such helper?

This idea of having access modifiers on  top level classes is getting out of hand. They are meaningless and illegal, and if the system accepts them it is a bug. It can only lead to confusion.

Remember, the modifier is for the class accessor, not for the factory method. The class accessor only exists in the enclosing class.  A top level class, by definition, has no enclosing class, and therefore no accessor, and thus no access modifier.

Ok I understand now the modifier is for the 'class accessor' , and there is no class accessor on the top level class, hence accesibility modifiers on it make no sense to define.

c) Given a top level class Top1 which code starts like this: "MOD class Top1 usingPlatform: platform = (..)(..)": Is it correct that any top level class Top2 can pull Top1 on it's slot, irrespective of access modier on Top1 primary factory method on the first line (even if MOD=private), for example like this:

top level class source: Top2 usingPlatform: platform andTop1: T1 = (|Top1_slot = T1|)

instantiation of Top2, e.g. in Workspace:  Top2 usingPlatform: platform andTop1: Top1.

See above.  The usage in the workspace has nothing to do with access modifiers.

I was feeling this is the case as I was doing the example. I felt I need to produce an example to frame my question, but this particular example lead to more confusion.

 

The classes Top1 and Top2 are accessible because they are in the IDE's root namespace,

Yes.

 

which the workspace can access because it's doesNotUnderstand: method consults that namespace.

Ok that info helps. I should look at that code but accept without looking.

 

The method #usingPlatform:andTop1: is accessible because it is a primary factory method, which is always public.

Yes, as you explained above -  re 'class accessors'?

Slot declaration: expression between | | in primary factory method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Variable declaration: expression between | | in instance method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

If I was very picky,  I'd say that we have instance slots and local slots.  But this fine.

So I suppose I should define terms it like this:

Instance slot declaration: expression between | | in primary factory method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Local slot declaration: expression between | | in instance method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Thanks,

Milan

 

--

Cheers, Gilad

[Gilad Bracha]

On Tue, Aug 10, 2021 at 12:30 AM Milan Zimmermann <milan.zi...@gmail.com> wrote:

The method #usingPlatform:andTop1: is accessible because it is a primary factory method, which is always public.

Yes, as you explained above -  re 'class accessors'?

Yes

So I suppose I should define terms it like this:

Instance slot declaration: expression between | | in primary factory method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Local slot declaration: expression between | | in instance method, irrespective whether it has a "=", "=::" or nothing to the right of the slot name.

Yes

--

Cheers, Gilad