Naming rules

[Idylog - Nicolas Granon <ng...@idylog.com>]

Following our "study" of "StackedViewManager" source code, we were wondering
why many class/methods/events... in Apache Royale are deliberately named
with different names than in the Flex SDK.

(for example, "StackedViewManager" instead of "ViewStack", "selectedView"
property instead of "selectedChild", "SelectedIndexChanged" event instead of
"IndexChangedEvent"...).

Is this kind of a guideline that we should follow ? Does it have any
technical reasons ? (name collisions ?), or maybe legal ?

Or maybe it's just a developer's choice without any other meaning ?

We intend to (more or less) "replicate" Flex components and we thought it
would be nice to keep as much as possible from Flex SDK syntax. But maybe
that is not a good idea ??

Nicolas Granon

RE: Naming rules

[Idylog - Nicolas Granon <ng...@idylog.com>]

Alex,

Your answer is quite interesting.

My (somewhat naïve) question made you say a lot of things about the "philosophy" behind Royale and about some fundamental design decisions.
Believe me, it helped a lot to better understand Royale as a whole.

Also, reading your answer, I realized that I may have suggested that we wanted to replicate *all* Flex components with Flex-like API.
That is not the case and I'm sorry for my ambiguous writing (my English is not so good).

We only want to replicate *some* components that we use a lot. We want that in order to keep most of the logic in our apps.
But your remarks about the importance of keeping strong types as much as possible has been heard ! And we will take that in account for our (modest) component adaptations (in the light of your comments, "adaptation" seems much more appropriate than "replication").

Regarding our (future) migration, your suggested steps are very sound. Of course, our apps are far from perfect and in some areas (oldest parts) the separation between view and control is not very good. We plan to take advantage of the migration to improve things...

Many thanks again

Nicolas Granon




> -----Message d'origine-----
> De : Alex Harui [mailto:aharui@adobe.com]
> Envoyé : dimanche 5 novembre 2017 08:11
> À : dev@royale.apache.org; ngranon@idylog.com
> Objet : Re: Naming rules
> 
> Great topic.  I think maybe we have enough folks to try to come up with
> some naming conventions.  My personal philosophy is that I'm bad at
> guessing names for things so it is better to just get something out
> there and let folks suggest better names.
> 
> I did have some considerations in mind though:
> 1) If the API wasn't 100% compatible with Flex, I was less inclined to
> retain the name
> 2) It was tempting to choose a W3C name from the HTML/JS/CSS specs over
> Flex names
> 3) Because HTMLElement is the basis for most UI widgets and thus
> innerHTML is always available, I chose to use properties like "text"
> and "html"
> instead of "label" for things like Button
> 4) Because I had some evidence that strong-typing was important to JS
> performance, I was tempted to choose APIs that would help retain type-
> checking.  The problem with event.target or ViewStack.selectedChild is
> that they end up being relatively base types.  In fact, we often choose
> Object and then strong-typing is truly broken.  So I pushed for a
> selectedView returning an IView (or something like that) to help retain
> types.  I get that it isn't as consistent as having every Navigator
> return selectedChild.  There can still be a selectedChild that is a
> more base type, and have more specific types on the subclasses if that
> makes it easier.
> 
> So like I said, all of this can be changed.  I'm not thinking of any
> API names that I think are awesome.
> 
> FWIW, we have Basic/Express components that are tilted towards
> HTML/JS/CSS as I described above.  I abandoned the effort to try to
> port the Flex framework on top of Basic/Express.  That would be 95% API
> compatible with Flex but would take a lot of folks to try to stabilize
> that much code.
> IMO, those are the two extremes. In the middle is making a MX-ish and
> Spark-ish component set.  It would try to use as many Flex APIs as it
> could, even if some weren't 100% backward compatible.  It would start
> out by only emulating the most popular APIs and folks could add more
> later with less worry about PAYG since MX and Spark weren't PAYG to
> begin with.
> Note that there are actually 100's of APIs just on Spark Button, so
> that's why I think it is impractical to try to emulate all of Button
> before moving on to the next component.  Maybe just label and click for
> starters.
>  The goal would be to et most of your MXML to compile without errors.
> It would probably not be a goal to get your existing AS that talks to
> these components to "just work".  If you have good separation of
> business logic from view logic, your business logic should "just work",
> but your UI-related ActionScript code might be expecting certain class
> inheritances or Flash APIs that may not work.  Again, 100%
> compatibility would not be a goal, just less migration work at the
> sacrifice of code size and
> performance.   That might turn out to be more frustrating (geez, it has
> the same name, but doesn't do the same thing), but maybe it would be
> useful to folks.
> 
> Thoughts?
> -Alex
> 
> On 11/4/17, 3:59 PM, "Idylog - Nicolas Granon" <ng...@idylog.com>
> wrote:
> 
> >Following our "study" of "StackedViewManager" source code, we were
> >wondering why many class/methods/events... in Apache Royale are
> >deliberately named with different names than in the Flex SDK.
> >
> >(for example, "StackedViewManager" instead of "ViewStack",
> "selectedView"
> >property instead of "selectedChild", "SelectedIndexChanged" event
> >instead of "IndexChangedEvent"...).
> >
> >Is this kind of a guideline that we should follow ? Does it have any
> >technical reasons ? (name collisions ?), or maybe legal ?
> >
> >Or maybe it's just a developer's choice without any other meaning ?
> >
> >We intend to (more or less) "replicate" Flex components and we thought
> >it would be nice to keep as much as possible from Flex SDK syntax. But
> >maybe that is not a good idea ??
> >
> >Nicolas Granon
> >
> >
> >
> >
> >

Re: Naming rules

[Alex Harui <ah...@adobe.com.INVALID>]

Great topic.  I think maybe we have enough folks to try to come up with
some naming conventions.  My personal philosophy is that I'm bad at
guessing names for things so it is better to just get something out there
and let folks suggest better names.

I did have some considerations in mind though:
1) If the API wasn't 100% compatible with Flex, I was less inclined to
retain the name
2) It was tempting to choose a W3C name from the HTML/JS/CSS specs over
Flex names
3) Because HTMLElement is the basis for most UI widgets and thus innerHTML
is always available, I chose to use properties like "text" and "html"
instead of "label" for things like Button
4) Because I had some evidence that strong-typing was important to JS
performance, I was tempted to choose APIs that would help retain
type-checking.  The problem with event.target or ViewStack.selectedChild
is that they end up being relatively base types.  In fact, we often choose
Object and then strong-typing is truly broken.  So I pushed for a
selectedView returning an IView (or something like that) to help retain
types.  I get that it isn't as consistent as having every Navigator return
selectedChild.  There can still be a selectedChild that is a more base
type, and have more specific types on the subclasses if that makes it
easier.

So like I said, all of this can be changed.  I'm not thinking of any API
names that I think are awesome.

FWIW, we have Basic/Express components that are tilted towards HTML/JS/CSS
as I described above.  I abandoned the effort to try to port the Flex
framework on top of Basic/Express.  That would be 95% API compatible with
Flex but would take a lot of folks to try to stabilize that much code.
IMO, those are the two extremes. In the middle is making a MX-ish and
Spark-ish component set.  It would try to use as many Flex APIs as it
could, even if some weren't 100% backward compatible.  It would start out
by only emulating the most popular APIs and folks could add more later
with less worry about PAYG since MX and Spark weren't PAYG to begin with.
Note that there are actually 100's of APIs just on Spark Button, so that's
why I think it is impractical to try to emulate all of Button before
moving on to the next component.  Maybe just label and click for starters.
 The goal would be to et most of your MXML to compile without errors.  It
would probably not be a goal to get your existing AS that talks to these
components to "just work".  If you have good separation of business logic
from view logic, your business logic should "just work", but your
UI-related ActionScript code might be expecting certain class inheritances
or Flash APIs that may not work.  Again, 100% compatibility would not be a
goal, just less migration work at the sacrifice of code size and
performance.   That might turn out to be more frustrating (geez, it has
the same name, but doesn't do the same thing), but maybe it would be
useful to folks.

Thoughts?
-Alex

On 11/4/17, 3:59 PM, "Idylog - Nicolas Granon" <ng...@idylog.com> wrote:

>Following our "study" of "StackedViewManager" source code, we were
>wondering
>why many class/methods/events... in Apache Royale are deliberately named
>with different names than in the Flex SDK.
>
>(for example, "StackedViewManager" instead of "ViewStack", "selectedView"
>property instead of "selectedChild", "SelectedIndexChanged" event instead
>of
>"IndexChangedEvent"...).
>
>Is this kind of a guideline that we should follow ? Does it have any
>technical reasons ? (name collisions ?), or maybe legal ?
>
>Or maybe it's just a developer's choice without any other meaning ?
>
>We intend to (more or less) "replicate" Flex components and we thought it
>would be nice to keep as much as possible from Flex SDK syntax. But maybe
>that is not a good idea ??
>
>Nicolas Granon
>
>
>
>
>