This is an automated email from the ASF dual-hosted git repository.
andreww pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new e592807 Update payg.md
e592807 is described below
commit e5928072da2ba1453ab6a8362df3d0e1e0407326
Author: Andrew Wetmore <[email protected]>
AuthorDate: Sat Aug 24 10:09:01 2019 -0300
Update payg.md
Made edits throughout to improve clarity and bring the text more in line
with current Royale reality (royality).
---
welcome/features/payg.md | 57 +++++++++++++++++++++---------------------------
1 file changed, 25 insertions(+), 32 deletions(-)
diff --git a/welcome/features/payg.md b/welcome/features/payg.md
index 7c64efb..6769d3e 100644
--- a/welcome/features/payg.md
+++ b/welcome/features/payg.md
@@ -21,67 +21,60 @@ description: Pay as you Go
# PAYG
-Pay as you Go
+Pay as you go
-_Pay as you go (PAYG)_ is a general principle for Royale whereby the SDK
framework code (the _Actionscript_ codebase used to create Royale SDK library
SWCs) supports incremental functionality in components. The goal is to provide
the possibility for a lower level of performance or memory impact of
applications built using the framework (compared to not applying __PAYG__ to
the framework code). __PAYG__ may imply a small performance or memory cost in
the framework to support its implement [...]
+_Pay as you go (PAYG)_ is a general principle for Royale. The SDK framework
code (the _ActionScript_ codebase used to create Royale SDK libraries) supports
incremental functionality in components. The goal is to provide components
that, used just as they are, require very little memory to provide the
component's most basic functions; and that can be extended to support functions
that are needed sometimes, but not always.
-## Philosophy
-
-To understand __PAYG__, it's very helpful to understand some background. The
opposite of __PAYG__ is "_Just in Case_" code. Classic Flex architecture took
this "_Just in Case_" approach and it resulted in a bloated framework. __Just
in Case__ relies very heavily on class inheritance and has a lot of code that
you might need for certain components. A perfect example of this is
[UIComponent](https://flex.apache.org/asdoc/mx/core/UIComponent.html){:target='_blank'}
which is close to 15,000 [...]
-
-__PAYG__ takes the opposite approach. Classes only contain the code necessary
for the minimum useful implementation to function. Instead of heavy reliance on
inheritance, __PAYG__ prefers composition and dependency injection. Instead of
additional features being baked in, they are composed and functionality
injected when needed. The theory is that this results in smaller, leaner
applications. Results seem to back up this theory.
-
-> One application which was ported from Flex4 to Royale was reduced from a
total size of 1.8MB down to less than 500KB of Javascript gzipped. There is
still potential in the Royale compiler to reduce the size even further. The
Flash version of this application seems to be even smaller, but exact numbers
are hard to determine because not all features are implemented in Flash.
+For example, the most basic thing a text-input component needs to do is accept
text the user provides. You might have lots and lots of instances of this
component in your application, and only a handful of them have to be able to
support entering _passwords_ by displaying as dots the characters the user
enters. For those instances only, we PAYG by extending the base component's
functionality and its "cost" in memory use and impact on the application's
performance.
-## What is 'Paying' in PAYG
+There may be a small performance or memory cost related to implementing PAYG
in the framework, but it saves a ton. Compiler options can also provide some
PAYG support with no additional framework overhead.
-'Paying' is defined as conscious decisions by developers to include
functionality that has a measurable and substantial performance or memory
impact. The ‘as you go’ implies ‘incremental functionality’. In simple terms,
it means that you do not include performance and memory ‘cost’ for
functionality you don’t use.
+## Philosophy
-The word 'Paying' can be replaced by the word 'Code'. Pay as You Go is
synonymous with 'Code as You Go'. That is (in general), any code which is not
essential for the functioning of the basic component should be composed to be
used "as you go" elsewhere. This elsewhere can be a subset, an alternate set, a
composable bead etc. The point is that "just in case" code should not be
included in the basic minimal useful implementation. It should be included only
when you want it, or opt in to " [...]
+The opposite of PAYG is "_Just in Case_" code. _Just in Case_ relies heavily
on class inheritance and has a lot of code that you might need only for certain
components in certain circumstances.
-The ‘paying’ aspect of PAYG does not include 'developer effort' as ‘payment’
or ‘cost’. This means that for some projects using a full __PAYG__ component
set, additional developer effort will be required, however the Royale project
team is working to reduce this by composing sets of general purpose components
that include ‘general purpose’ functionality (See [Doesn’t supporting PAYG have
its own
cost?](welcome/features/payg.html#doesnt-supporting-payg-have-its-own-cost)
below).
+Classic Flex architecture took the _Just in Case_ approach and it resulted in
a bloated framework. For instance,
[UIComponent](https://flex.apache.org/asdoc/mx/core/UIComponent.html){:target='_blank'}
is close to 15,000 lines of code, with hundreds of methods that are only
needed in specific situations. Since _UIComponent_ is the base class for every
UI component in Flex, every Flex application carries around every line of this
code whether it needs it or not. Moreover, much of the _Just [...]
-## How is ‘measurable and substantial’ defined to determine thresholds for
default functionality?
+PAYG takes the opposite approach. Classes only contain the code necessary for
the minimum useful implementation to function. Instead of heavy reliance on
inheritance, PAYG prefers composition and dependency injection. Instead of
additional features being baked in, they are composed and functionality
injected when needed. The theory is that this results in smaller, leaner
applications. Results seem to back up this theory.
-Determining whether something has merit for inclusion in default functionality
or is categorised into ‘as you go’ is something that has generated discussions
in the mailing lists and has resulted in disparate views. Perhaps part of the
reason for this is a lack of clarity and/or consensus as to whether ‘paying’
includes developer effort or not (see What is
[Paying](welcome/features/payg.html#what-is-paying-in-payg) above).
+> One application which was ported from Flex4 to Royale was reduced from a
total size of 1.8MB to less than 500KB of JavaScript gzipped. There is still
potential in the Royale compiler to reduce the size even further. The Flash
version of this application seems to be even smaller, but exact numbers are
hard to determine because not all features are implemented in Flash.
## Why PAYG?
-To target Javascript, the Royale SDK and components needed to be substantially
different to the legacy Flex 4 SDK which is SWF-only. Given this need to make
large changes, the opportunity was also taken to review general improvements to
the SDK component architecture to address some common criticisms of the Flex 4
component set. One of those criticisms (the size of compiled applications)
relates to the size of some of the Flex 4 base classes which, in simple terms,
is the opposite of PAYG.
+To target JavaScript, the Royale SDK and components needed to be substantially
different from the legacy Flex 4 SDK and components, which were designed to
compile into Flash applications and libraries. Since we had to make substantial
changes throughout the code base, we took the opportunity to review how we
could make general improvements to the SDK component architecture to address
some common criticisms of the Flex 4 component set. One of those criticisms
(the size of compiled applica [...]
-Implementing __PAYG__ in Royale has the goal of maintaining the possibility of
a full range of functionality, but making it more incremental/opt-in.
+Implementing PAYG in Royale has the goal of maintaining the possibility of a
full range of functions while keeping application size and the cost of runnin
an app as small as possible.
-## Doesn’t supporting PAYG have its own cost?
+## How we define default functionality
-### Performance
+Determining whether something should be in a component's default functionality
or should be added ‘as you go’ is dynamic conversation the team engages in. You
are welcome to [join in and add your
insights](https://royale.apache.org/mailing-lists/){:target='_blank'}!
-Performance cuts both ways. __PAYG__ may contribute to performance costs,
because there is some overhead in supporting a runtime based composition model.
On the other hand, __"Just in Case"__ code is not being run, so that more than
likely offsets the overhead. Moreover, the general principle is that
establishing the ability to compose functionality (especially via MXML) is
worth the overhead. For features that are opt-in via the compiler, these
features may not have an extra framework cost.
+## What are we 'Paying' in PAYG?
-### Developer Effort
+'Paying' is the conscious decisions by developers to include functionality
that has a measurable and substantial performance or memory impact. The ‘as you
go’ implies adding ‘incremental functionality’ as needed, and only paying for
what you need. In simple terms, it means that you do not pay performance and
memory ‘costs’ for functionality you don’t use.
-Because there can be extra effort to compose incremental functionality for
common use cases, it would likely result in extra developer effort being
required if the developer was using a full __PAYG__ approach to development on
every project.
+Pay as You Go is synonymous with 'Code as You Go'. Whichever term you prefer,
the principle is the same: any code which is not essential for the basic
component to perform its core functions should be composed elsewhere and added
to instances of the component that need it. This 'elsewhere' can be a subset,
an alternate set, a composable bead (see below), etc.
-For this reason, the __Express__ component set exists which has pre-composed
components that feature combinations of functionality to suit more general use
cases. The intention behind this is to reduce the time and effort required in
the use of common components by including the more commonly needed
functionality. The vision is that there should be a collection of component
sets which compose the functionality required for specific types of
applications. This can help balance ease of dev [...]
+The ‘paying’ aspect of PAYG does not include _developer effort_ in the
‘payment’. For some projects that want to use a full PAYG component set,
especially if they are migrating an existing Flex app to Royale, additional
developer effort will be required. However, Royale provides [component
sets](https://apache.github.io/royale-docs/component-sets.html){:target='_blank'}
that supply most if not all of the most commonly-used components, and a
growing collection of _beads_ (see below) that [...]
-The same can be applied to [Jewel](component-sets/jewel.html) component set
that is designed with __PAYG__ in mind but tries to balance towards the
usability of the framework and to not be so strict.
+The _Express_ component set has pre-composed components that feature
combinations of functionality to suit general use cases. This reduces the time
and effort required to deploy common components by including their more
commonly needed functionality, helping balance ease of development against
__PAYG__ benefits.
-## PAYG vs DRY
+Similarly, the [Jewel](component-sets/jewel.html){:target='_blank'} component
set is designed with PAYG in mind but tries to balance towards the usability of
the framework and to not be PAYG-strict.
-Another software design concept is __DRY__ (_Don't Repeat Yourself_). __PAYG__
can sometimes be at odds with __DRY__. Considering that additional
functionality would need to be in a different class, this can lead to code
repeat and multiple classes which have a lot of the same logic.
+## PAYG vs DRY
-Despite this, we feel that the benefits of __PAYG__ out way the costs of
sometimes failing to adhere to __DRY__.
+Another software design concept is _DRY_ (_Don't Repeat Yourself_). PAYG can
sometimes be at odds with DRY. Considering that additional functionality would
need to be in a different class, this can lead to multiple classes which have a
lot of the same logic. Despite this, we feel that the benefits of PAYG outweigh
the costs of sometimes failing to adhere to DRY.
-However, we don't want to ignore __DRY__ and it's worth noting that it's not
always an issue, and the cost can be mitigated. Many of these cases are simply
alternate implementations of the same type of component. When picking the
component set, the minimal usable implementation should be selected. If the
larger implementation is needed, and is used consistently across the
application, this code duplication might never make it into the end
application. Additionally, use of subclasses in e [...]
+However, we don't want to ignore DRY. Using subclasses in extended components
can result in less code duplication.
-> An additional technique which is used frequently in framework code is the
use of utility classes or top level functions to implement commonly used code
that is needed across different components. This utility code will only be
included if it's actually used, and only be included once no matter how many
times it's used. Utility code should be small and serve a single purpose.
+> An additional technique which is used frequently in framework code is the
use of utility classes or top-level functions to implement commonly-used code
that is needed across different components. This utility code will only be
included if it's actually used, and is only included once no matter how many
times it's used. Such utility classes should be small, and each should serve a
single purpose.
## How does PAYG get implemented?
### Strands and Beads
-The [Strands and Beads](welcome/features/strands-and-beads.html) concept is a
metaphor for adding extra functionality (beads) onto a component (strand).
__Beads__ represent the modular units of functionality that can be selected and
composed together to configure functionality added to the __Strand__ (base
component). Component sets such as ‘Express’ include more general functionality
which may into reduce developer effort for the general case of application
development.
+The [Strands and Beads](welcome/features/strands-and-beads.html) concept is a
metaphor for adding extra functionality (beads) onto a component (strand).
_Beads_ are the modular units of functionality that can be added to the
_strand_ (base component).
### Compiler
-Through compiler options (i.e, initialised vs. uninitiliased variables) Royale
is providing __PAYG__ capabilities too.
-
+Through compiler options (i.e, initialised vs. uninitiliased variables) Royale
provides further PAYG capabilities.
