First pass. #1
First pass. #1
Conversation
| result in unpredictable and counterintuitive behavior depending on the context. | ||
| This unpredictable behavior often makes partials difficult-to-impossible to | ||
| optimize by both glimmer and the browser. As an example, using partials within | ||
| an ‘each’ manifests this performance anti-pattern most consistently. |
There was a problem hiding this comment.
Suggest replacing with the following attempt to be more approachable and actionable
Using the {{partial}} helper allows a chunk of handlebars template to be inserted into another, without any change to the template context. We sometimes refer this piece of handlebars that's inserted as a partial.
Because there's no way to know exactly what a partial is going to do without knowing the template context of where it's used, it's very hard for developers to confidently debug, and inherently hard for browsers and ember's view layer to optimize.
|
|
||
| By contrast, components have a clear contract with the outside world, and should | ||
| be strongly considered as a favorable alternative when reuse and composability | ||
| is desired. Partials are not needed to modify behavior from core within extended. |
There was a problem hiding this comment.
This is in a public github repo. Do we want to use terms like core and extended here?
| * Utilizing the component’s `{{yield}}` to enable variable layouts | ||
| * Utilizing a component instead of a partial (and swapping out the implementation | ||
| of that component for one specific to extended or core) | ||
| * Utilizing the `{{component` helper with the name of a component |
There was a problem hiding this comment.
We should really provide at least one example for each of these. In training workshops, I have presented similar bullet points to these, and I usually end up getting blank faces in response.
|
|
||
| * Utilizing the component’s `{{yield}}` to enable variable layouts | ||
| * Utilizing a component instead of a partial (and swapping out the implementation | ||
| of that component for one specific to extended or core) |
There was a problem hiding this comment.
What's "the implementation of that component"? component.js?
If so, it may be better to advise developers to employ the strategy pattern here, where specific things used by the component can be provided from the outside.
| occur multiple times for a single paint of the page. | ||
|
|
||
| For work that only needs to be done once on initial render, schedule the work | ||
| from `didInsertElement` (see discussion in the very next section). |
There was a problem hiding this comment.
Now that this is organized in a less linear way, let's direct users to the appropriate section more explicitly
| Manipulating or storing data at the incorrect locality often introduces | ||
| mutation backflow, potential memory leaks, issues with asynchronous teardown, | ||
| and unintentional and inconsistent side-effects. All of these scenarios can | ||
| adversely affect performance, code readability, and maintainability. |
There was a problem hiding this comment.
This whole section is rather vague and is asking for rigid mis-interpretation and mis-application. What's a "state tree"? I still have no idea what "mutation backflow" is.
As currently written, I cannot imagine that we have consensus on this.
| Manipulating or storing data at the incorrect locality often introduces | ||
| mutation backflow, potential memory leaks, issues with asynchronous teardown, | ||
| and unintentional and inconsistent side-effects. All of these scenarios can | ||
| adversely affect performance, code readability, and maintainability. |
There was a problem hiding this comment.
This whole section is rather vague and is asking for rigid misinterpretation and misapplication. What's a "state tree"? I still have no idea what "mutation backflow" is. Let's challenge ourselves to simplify the language we use for documents like these (i.e., "incorrect locality" vs "wrong place")
| component has already rendered when a child component mutates an object owned | ||
| or utilized by the parent component. This forces the parent component to need | ||
| to re-render, and is one of several causes of what we refer to as a backtracking | ||
| rerender. |
There was a problem hiding this comment.
I do not think we need to coin a new term for this, nor do I think this particular term adds clarity to the phenomenon it is intended to describe. Let's see if we can stick to a pattern of
- Don't do this
- Here's why it's bad
- Do this instead
Without coming up with a special new name for each antipattern.
| activating / deactivating) | ||
| * Local State (state that should live and die based on the display | ||
| lifecycle of a single component, also known as "UI State" or | ||
| "Component State") |
There was a problem hiding this comment.
While this tree makes sense in a variety of situations, I'm not comfortable with just tossing this out there with a couple of sentences of explanation. State management is one of the biggest challenges that developers have with their apps, and incomplete/cursory guidance in this area can be worse than no guidance at all.
| component. For Application or Route level state the action should be sent to a | ||
| route or service. | ||
|
|
||
| ### Sideways Communication |
There was a problem hiding this comment.
There has to be a better way to describe this. With data down, actions up, don't go sideways -- I feel like I need a compass to build my app.
Let's focus more on example-driven guidance, and challenge ourselves to avoid coining any new terms. The learning curve is plenty steep already, and new jargon is a new barrier to enter.
There was a problem hiding this comment.
The learning curve is plenty steep already
Does anybody see this as a fundamental issue?
Just looking through these issues really lays bare how difficult it is to work with ember and reason about executing complex features. The cognitive load is enormous.
In my experience, isolated examples are not enough. Negotiating this complexity holistically is what's required to build an app.
|
Can we merge this yet?? |
Includes guides with the following information:
These sections represent the areas of the document that @runspired prepared that have wide ranging agreement.