@dbazile wrote:

In React, they use React.PropTypes for some rudimentary validation of properties passed in by client code which serves as its own type of documentation. Considering the absence of such a mechanism in Ember, I’d like to know how are others dealing with the task of documenting the external attribute requirements for a component?

Ideas thus far

Given the following contrived example:

export default Ember.Component.extend({
  someRequiredProp: null,
  someOptionalProp: false
});

1. Reopening Ember.Component and adding some assertion-type method, allowing components to do something like:

export default Ember.Component.extend({
  someRequiredProp: null,
  someOptionalProp: false

  didInitAttrs() {
    this.assertHasAttr('someRequiredProp');
  }
});

Problems with this approach

• Messing with Ember core classes is going over to the Dark Side.

​2. Having jsdocs above the class, ala:

export default Ember.Component.extend({
  /*
   * @required
   * @type object
   */
  someRequiredProp: null,

  /*
   * @optional
   * @type bool
   */
  someOptionalProp: false,
});

Problems with this approach

• Lots of boilerplate
• Even with the highest level of developer discipline, all jsdocs eventually fall out of date or are flat out ignored from the start.
• This crowds the source code as each external attr now has 5+ leading lines of visual noise.

3. Writing unit tests that exercise the props.

test('can instantiate', function (assert) {
  assert.doesNotThrow(() => this.subject({
    someRequiredProp: {}
  });
});

test('throws when missing required props', function (assert) {
  assert.throws(() => this.subject({
    someRequiredProp: null
  });
});

test('throws when adding junk to required props', function (assert) {
  assert.throws(() => this.subject({
    someRequiredProp: 'bet you were not expecting a string lol'
  });
});

Problems with this approach

• Doesn’t necessarily scale down. Who writes unit tests for small components? Maybe at that level it doesn’t matter because failures will be relatively localized?
• Obviously more code than #1 and #2

Posts: 3

Participants: 3

Read full topic