Scrubbing the API

We want to clean up the API of SproutCore to consistently follow best practices (outlines below). API that does not conform to the rules below should be moved to the “deprecated” directory in SproutCore and replaced with conforming API (or it may simply be removed if it is not needed).

Just before we release, the deprecated directory will be moved into its own framework. Developers who want to use these old APIs can include the Deprecated.framework.

Current Status

core.js and most files in the “system” directory have been reviewed. The view layer is currently being rewritten and reviewed during that process.

Currently we still need help viewing the mixins, controllers, models, and server directories.

API Best Practices

This is still a work in progress. It will be expanded in the next few days.

General Naming

• Any property that does not begin with an underscore (“_”) MUST always be accessed using set() and get(). There are a few exceptions where you may not do this if performance is a particular issue but this must be carefully documented. Keep this to a minimum though; always use get() and set().

• Any property that begins with an underscore (“_”) MUST NOT be accessed using set() and get(). An underscore indicates an internal property that could change anytime without using get() and set().

• Public methods must not begin with an underscore.

• “Protected” methods (methods you intended to be used by subclasses), also should not begin with an underscore.

• Private methods must begin with an underscore. These should not be used by subclasses.

• If you have a common private method or property name (e.g. _value or _content or _contentDidChange()), and you think it is likely a subclasser might try to use the same method or property name, you should prefix with _className. For example, _value might become _myClass_value. This only applies to private methods or properties.

General Coding Guidelines

• If your method does not have an obvious return value, return “this”. This way your method can be used in chaining. The one exception is a method that you expect subclassers to override. For these methods it is best to ignore the return value unless there is an obvious need for a return value, since a subclasser us likely to forget to return the correct value.

Property Naming

• value Represents the current state of a view or class. If the class instance state changes, you should expect the value of this property to be replaced, not modified. For example, if the “value” property of a TextField is “Hello World”, and you edit the text field, it will replace that string with the new value of the text field. Likewise, if you set a value property to an array and the object changes, you should expect it to replace the array, not to modify it. If a view or class only represents one “value”, you should name the property value. Otherwise, you might use something more specific (e.g. “minimum”, “maximum”, etc.)

• content Represents an object the view or class is working on. If class instance changes state, you should expect it to modify its content object, not replace it. For example, if you set the “content” property of a ListView to an array, then reorder the list, you should expect it to modify the array, not to replace it.

• content…Key Many times it makes sense for a view or class to have both a value (or several types of values) and a content that somehow maps to that value. You can configure this mapping with a property named “content…Key”, where the middle part is replaced with the name of the value property. For example, an SC.TextFieldView has a “value” property and a “content” property. If you set the “content” property to an object and then set the “contentValueKey” property to “title”, then when the TextFieldView value changes you can expect it to also modify the “title” property on the content object.

Method Naming

• compute…() A method that simply computes a value is often times best implemented as computed property. Sometimes, however, you want to recompute the value everytime the method is called. For this purpose, it is usually best to implement a method. Name the method “compute…()”, to indicate that the method will likely perform an expensive operation to compute the value. If the method in question returns a value but it is not expensive, do not name it “compute…”. This way a developer can guess which operations are expected to be expensive.

Observers

• …DidChange – Usually you want to name a property “fooDidChange()” to clearly describe that you expect it to execute whenever “foo” changes. foo can map to the property you are observing or to any other descriptive term. For example, you might name an observer that runs whenever the clippingFrame or visibility changes something like “visibleFrameDidChange()”