From b8f302c8f5427e715770962ba7290834c94bef72 Mon Sep 17 00:00:00 2001 From: Brandon Tilley Date: Sat, 21 Dec 2013 22:47:25 -0800 Subject: [PATCH] Add plugin 'best practices' documentation --- site/public/documentation/plugins.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/site/public/documentation/plugins.md b/site/public/documentation/plugins.md index 901bd8a..bae95cc 100644 --- a/site/public/documentation/plugins.md +++ b/site/public/documentation/plugins.md @@ -175,3 +175,13 @@ setTimeout(function() { }, 5000); ``` + +Best Practices +-------------- + +There are a few things you can do to make your plugin all it can be: + +1. Make your plugin very small; ideally, it should do only *one thing* very well. Be extremely liberal with splitting plugins into smaller plugins, which makes them easier to understand, test, and compose. It's easy to say "this plugin renders the Earth," but it really renders oceans, land masses, and borders. +2. Use function generators to generate your plugin (as described above in "Plugin Generators"), even if it doesn't take any configuration options. It makes for a more consistent API, and allows you to add the ability to specify configuration options in the future without changing the base API. +3. Make configuration optional if at all possible. Write your plugin so that it checks for missing values and uses sensible defaults. +4. Only publish public data and API methods to `planet.plugins.pluginName`, where `pluginName` is the name of your plugin.