<commit_before>﻿% Enyo Dos and Don'ts

A while back, the Framework Team began keeping a list of items for team members
to consider before submitting code for peer review.  As the list grew, we
realized that it could be useful to the wider community of app developers.  Thus
we are pleased to present the current document.

The content is divided into sections aimed at particular groups of developers;
we begin by addressing a general audience, then move on to discuss the more
specialized responsibilities of those creating shared code.  We suggest that you
start reading at the beginning and stop when the content no longer seems
relevant to your specific role.

## I'm Developing an Enyo/Moonstone Application...

Welcome to the team!  Here are some things that all developers should keep in
mind when writing apps using Enyo and Moonstone:

* **Don't break encapsulation.**

    * Avoid using `$` more than once on a given line:

        ```javascript
            this.$.child.$.childsChild    // bad idea
        ```

    * Don't reach into the parent's other components:

        ```javascript
            this.parent.$.parentsChild    // also a bad idea
        ```

    For more on this topic, see [Encapsulation in Enyo](encapsulation-in-enyo.html).
     
* **Most published properties should have change handlers (or data bindings).**

    A common bug occurs when a property is used only at create/render time;
    later, when someone calls `set("myProperty", <myValue>)`, nothing happens
    because there is no change handler to enable the property to change at
    runtime.

    This situation can easily go undetected.  Samples may look fine because the
    properties are passed in at create time.  The normal pattern is to put the
    code that uses a property in a change handler, and to call that handler from
    `create()` (or from `render()`, if the handler needs to send events--see the
    following).

* **Do not send events from `create()`; if initial events must be sent, send them
    from `render()`.**

    The problem with sending events from `create()` is that event handlers in
    the owner or elsewhere often need to reference other components.  `create()`
    is called as items are being created, meaning that at the time Component A's
    `create()` is called, all components after it (e.g., Components B and C)
    have yet to been created.  As a result, if you have a handler for A's event
    that references `this.$.B`, it will throw an undefined error.

    Firing initial events from `render()` is safer, since all components have
    been created by the time `render()` is called.

* **Handlers for `onSetupItem` events should usually return `true`, stopping
    propagation of the event.**
    
    Failure to return `true` may cause problems with nested repeaters or lists,
    and will certainly make the program run more slowly due to the extra
    dispatching taking place for each item.<commit_msg>Fix grammar<commit_after>﻿% Enyo Dos and Don'ts

A while back, the Framework Team began keeping a list of items for team members
to consider before submitting code for peer review.  As the list grew, we
realized that it could be useful to the wider community of app developers.  Thus
we are pleased to present the current document.

The content is divided into sections aimed at particular groups of developers;
we begin by addressing a general audience, then move on to discuss the more
specialized responsibilities of those creating shared code.  We suggest that you
start reading at the beginning and stop when the content no longer seems
relevant to your specific role.

## I'm Developing an Enyo/Moonstone Application...

Welcome to the team!  Here are some things that all developers should keep in
mind when writing apps using Enyo and Moonstone:

* **Don't break encapsulation.**

    * Avoid using `$` more than once on a given line:

        ```javascript
            this.$.child.$.childsChild    // bad idea
        ```

    * Don't reach into the parent's other components:

        ```javascript
            this.parent.$.parentsChild    // also a bad idea
        ```

    For more on this topic, see [Encapsulation in Enyo](encapsulation-in-enyo.html).
     
* **Most published properties should have change handlers (or data bindings).**

    A common bug occurs when a property is used only at create/render time;
    later, when someone calls `set("myProperty", <myValue>)`, nothing happens
    because there is no change handler to enable the property to change at
    runtime.

    This situation can easily go undetected.  Samples may look fine because the
    properties are passed in at create time.  The normal pattern is to put the
    code that uses a property in a change handler, and to call that handler from
    `create()` (or from `render()`, if the handler needs to send events--see the
    following).

* **Do not send events from `create()`; if initial events must be sent, send them
    from `render()`.**

    The problem with sending events from `create()` is that event handlers in
    the owner or elsewhere often need to reference other components.  `create()`
    is called as items are being created, meaning that at the time Component A's
    `create()` is called, all components after it (e.g., Components B and C)
    have yet to be created.  As a result, if you have a handler for A's event
    that references `this.$.B`, it will throw an undefined error.

    Firing initial events from `render()` is safer, since all components have
    been created by the time `render()` is called.

* **Handlers for `onSetupItem` events should usually return `true`, stopping
    propagation of the event.**
    
    Failure to return `true` may cause problems with nested repeaters or lists,
    and will certainly make the program run more slowly due to the extra
    dispatching taking place for each item.
{'fraction_non_alphanumeric': 0.06311503223617237, 'fraction_numerical': 0.0, 'mean_word_length': 3.3345588235294117, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1880058', 'n_tokens_mistral': 1482, 'n_tokens_neox': 1408, 'n_words': 854}