Design Patterns

These are design patterns to avoid, and best practices to use instead.

Don't Throw Exceptions - Return Structured Data

A common temptation is to throw exceptions for a user visible message indicating why an operation cannot be completed.

In general, exceptions should only be thrown for bugs in nuclide code. For example, when a function is called with invalid arguments. The general rule is that if you expect your caller to catch the exception you should not be throwing an exception. Instead encode the thrown value into your function's return type using Flow's disjoint unions. Throwing exceptions hides the contract of your function from the programmer and the Flow type system.

Don't Poll - Use Promises or Event Notifications

Avoid polling for a condition to occur with setTimeout. Polling is inefficient and error prone.

Prefer to get notified of the condition using Promise completion, or an event notification. The EventEmitter.once API is handy for one time notifications. If you can't find the event you need add it.

Subscribe to the Right Events

Atom makes it easy to subscribe to events on TextEditors. TextEditors are often the incorrect object to get notifications from. TextEditors are UI abstractions representing an editor window pane. There may be multiple TextEditors open for a given underlying file. Many of our packages care about changes to files, not changes to the Atom UI. Subscribing to the TextEditor onDidChange/onDidSave/onDid* is almost always the wrong place to subscribe.

Instead we have added the text-event-dispatcher package to surface events on changes to the underlying TextBuffer. In the future we will push these events into the Atom TextBuffer class.