Jetpack/Design Guidelines: Difference between revisions

Jetpack/Design Guidelines (view source)

Revision as of 01:19, 9 February 2010

266 bytes removed , 9 February 2010

reformatted and updated

MykMelez

canmove, Confirmed users

2,056

edits

@@ Line 1: / Line 1: @@
+= Goals =
 Jetpack is intended to improve the following areas of Firefox extensibility:
-* Compatibility. Large numbers of current addons require work at each major release to maintain compatibility. A major design goal for Jetpack is to provide a base set of functionality needed to extend the browser and create a stable set of interfaces around those features to eliminate these incompatibility problems. In a nutshell, Keep Addons Working Across Major Releases! for the benefit of end-users who like using addons and developers who don't want to chase more frequent Firefox and other product release trains.
+== Compatibility ==
+Large numbers of current addons require work at each major release to maintain compatibility. A major design goal for Jetpack is to provide a base set of functionality needed to extend the browser and create a stable set of interfaces around those features to eliminate these incompatibility problems. In a nutshell, Keep Addons Working Across Major Releases! for the benefit of end-users who like using addons and developers who don't want to chase more frequent Firefox and other product release trains.
-* Security. Currently, addons can "do anything" once installed. Jetpack is being designed to restrict, isolate, and sandbox the set of capabilities it provides to improve security for users, by extending to addons only the capabilities they need, restrict access to internal implementation details of those capabilities, and make their use of those capabilities more visible to code reviewers and users.
+== Security ==
+Currently, addons can "do anything" once installed. Jetpack is being designed to restrict, isolate, and sandbox the set of capabilities it provides to improve security for users, by extending to addons only the capabilities they need, restrict access to internal implementation details of those capabilities, and make their use of those capabilities more visible to code reviewers and users.
-* Usability. Historically, Firefox API design has been limited by the requirements of XPCOM/XPIDL and has not taken advantage of improvements in the expressiveness of the JavaScript language and achievements in API ergonomics by JavaScript libraries. Jetpack will provide a JS-only API with a strong focus on simplicity, productivity, and flexibility.
+== Usability==
+Historically, Firefox API design has been limited by the requirements of XPCOM/XPIDL and has not taken advantage of improvements in the expressiveness of the JavaScript language and achievements in API ergonomics by JavaScript libraries. Jetpack will provide a JS-only API with a strong focus on simplicity, productivity, and flexibility.
+= Principles =
+Jetpack APIs should be:
-* <strike>Generative</strike>
+* simple, eschewing obfuscation
-* The goals of Jetpack APIs and development system for extending the browser are
+* minimal, providing functionality that meets common use cases, not every possible case
-** Easy to learn
+* easy to learn and use, even without documentation
-** Easy to use, even without documentation
+* hard to misuse, whether intentionally or unintentionally
-** Hard to misuse
+* consistent, both within each API and across the entire API set provided by Jetpack
-** Easy to read and maintain code that uses it
+** similar object properties and method parameters should have similar names
-** Sufficiently powerful to satisfy requirements
+** similar method parameters should be in the same position in call signatures
-** Clear and consistent APIs -- guidelines will outline naming conventions (CamelCase naming, etc..?), placement and position of arguments (jquery like? options, arg, callbacks?)
+* flexible, so adaptable to unanticipated use cases (although not at the expense of overgenericism)
-** Minimal API Set  -- Make sure we have solid use cases for each API and have reduced to common root.
+* reusable, for use in higher-level and composed APIs
-** Complete, Comprehensive & Orthogonal APIs across the full API set - find all the common attributes/arguments (add, remove, get, set) make a grid and make sure its complete.
+* completely specified, in Jetpack Enhancement Proposals (JEPs)
-** Consistent Error Handling to Enable Debugging.
+* completely documented, in Jetpack documentation
-** Testing -- APIs will be implemented in test driven development process.  write the test first, then develop support for the api to pass the test.
-** Extensibility.  The goals list above all strive to keep the base set of supported APIs as minimal and solid as possible, and then allow extensibility for creating additional experimental features.
+= References =
-These goals inspired by lessons learned in jquery and FUEL library development and present in a talk by jresig (http://video.google.com/videoplay?docid=-474821803269194441# ) and papers on API Design including
+* [http://video.google.com/videoplay?docid=-474821803269194441# Best Practices in Javascript Library Design]
-http://queue.acm.org/detail.cfm?id=1255422
+* [http://queue.acm.org/detail.cfm?id=1255422 API Design Matters]
-http://lcsd05.cs.tamu.edu/slides/keynote.pdf
+* [http://lcsd05.cs.tamu.edu/slides/keynote.pdf How to Design a Good API and Why it Matters]
-http://neuroning.com/2006/11/19/on-api-design-guidelines
+* [http://neuroning.com/2006/11/19/on-api-design-guidelines On API Design Guidelines]
+* [http://queue.acm.org/detail.cfm?id=1071731 Programmers Are People, too]