canmove, Confirmed users
737
edits
Jetpack/Design Guidelines: Difference between revisions
m
moved Labs/Jetpack/Design Guidelines to Jetpack/Design Guidelines
(explicitly label as a draft) |
m (moved Labs/Jetpack/Design Guidelines to Jetpack/Design Guidelines) |
||
| (4 intermediate revisions by 2 users not shown) | |||
| Line 42: | Line 42: | ||
let panel = new Panel({ content: "...", width: 200, height: 300 }); | let panel = new Panel({ content: "...", width: 200, height: 300 }); | ||
// panel.content, panel.width, and panel.height are defined. | // panel.content, panel.width, and panel.height are defined. | ||
It should also be possible to construct instances of an object by calling its constructor without the <code>new</code> operator. | |||
let panel = require("panel").Panel(); | |||
Properties that don't have to remain constant over the life of an instance should be settable and deletable after construction by directly setting and deleting the properties. | Properties that don't have to remain constant over the life of an instance should be settable and deletable after construction by directly setting and deleting the properties. | ||
| Line 59: | Line 63: | ||
delete panel.height; | delete panel.height; | ||
Properties that can accept either a single or multiple unordered values should be settable to either a single or an array of values, and it should be possible to add and remove individual values from their set of values by calling add and remove methods on the property: | |||
let | let Foo = require("foo").Foo; | ||
let | let foo = new Foo(); | ||
foo.bar = ["a", "b", "c"]; | |||
foo.bar.add("d"); | |||
foo.bar.remove(["a", "b"]); | |||
// foo.bar now has the values "c" and "d". | |||
It should also be possible to enumerate multi-value properties via for each.. in loops: | |||
for each (let val in foo.bar) { ... } | |||
The add/remove methods on multi-value properties should remove primitive values (strings, numbers, booleans) by value and non-primitive values by reference: | |||
foo.bar.add("a"); | |||
foo.bar.add(function() alert("foo!")); | |||
let c = function() alert("bar!"); | |||
foo.bar.add(c); | |||
foo.bar.remove("a"); | |||
// a is removed (the string "a" is a primitive value). | |||
foo.bar.remove(function() alert("foo!")); | |||
// function() alert("foo!") is not removed (the function being removed | |||
// refers to a different instance of a function that was added). | |||
foo.bar.add(c); | |||
// c is removed (it refers to the same instance of a function that was added). | |||
Method names should be verbs, e.g. <code>show</code>, <code>post</code>. Property names should be the simplest accurate conventional or idiomatic label for their value (e.g. <code>persistent</code> for the boolean property of a visual feature that specifies whether or not the feature remains visible all the time). | Method names should be verbs, e.g. <code>show</code>, <code>post</code>. Property names should be the simplest accurate conventional or idiomatic label for their value (e.g. <code>persistent</code> for the boolean property of a visual feature that specifies whether or not the feature remains visible all the time). | ||
| Line 96: | Line 122: | ||
A quick technique for differentiating these is to consider the simple imperative sentence "[verb] it": "upload it" sounds right, while "sign in it" doesn't (it should be "sign it in"), suggesting that the former is a verb comprising a stem and affix while the latter is a phrasal verb. | A quick technique for differentiating these is to consider the simple imperative sentence "[verb] it": "upload it" sounds right, while "sign in it" doesn't (it should be "sign it in"), suggesting that the former is a verb comprising a stem and affix while the latter is a phrasal verb. | ||
Event callback properties should be multi-value properties, so it should be possible to specify multiple callbacks for an event by assigning an array to the event's callback property or by calling its <code>add</code> and <code>remove</code> methods: | |||
let foo = function() { ... }; | let foo = function() { ... }; | ||
| Line 116: | Line 142: | ||
Interfaces should take advantage of composition to reduce repetition and complexity. For example, interfaces that display a panel should solicit it from their consumers in the form of a property that accepts a Panel object. | Interfaces should take advantage of composition to reduce repetition and complexity. For example, interfaces that display a panel should solicit it from their consumers in the form of a property that accepts a Panel object. | ||
The names of modules, singletons, constructors, properties, and methods should be the simplest distinct word or phrase that accurately describes the thing being named, with single full words being preferable to acronyms (e.g. Request rather than XHR), abbreviations (e.g. Separator instead of Sep), and phrases (e.g. <code>persistent</code> rather than <code>alwaysDisplay</code> and <code>precede</code> instead of <code>insertBefore</code>). | |||
= References = | = References = | ||