From 81adb15ad65757ba5fff734bcc10ae39bfe294eb Mon Sep 17 00:00:00 2001 From: Hixie Date: Fri, 24 Oct 2014 13:34:40 -0700 Subject: [PATCH] Docs: Strawman design principles Review URL: https://codereview.chromium.org/676093002 --- specs/design.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 specs/design.md diff --git a/specs/design.md b/specs/design.md new file mode 100644 index 00000000000..a57eeeddf44 --- /dev/null +++ b/specs/design.md @@ -0,0 +1,32 @@ +Design Principles +================= + +* There should be no objects that represent live state that reflects + some other state, since they are expensive to maintain. e.g. no + HTMLCollection. + +* Property getters should be efficient. If an operation is inefficient + it should be a method instead. e.g. document.getForms(), not + document.forms. + +* There should be no APIs that require synchronously computing layout + (or other expensive operations). + +* Any API that can be implemented in terms of another is a convenience + API and should be implemented in a framework, not as part of the + core. e.g., no document.forms. + + - having APIs for performance reasons is fine (e.g. querySelector() + could be implemented by crawling but it would be so much faster if + it could use the runtime's ID hashtables that it's ok to support + natively) + +* APIs that encourage bad practices should not exist. e.g., no + document.write(), innerHTML, insertAdjacentHTML(), etc. + +* If we expose some aspect of a mojo service (e.g. touch events) we + should expose/wrap all of it (e.g. mousewheel) so that there's no + cognitive cliff when interacting with that service + +* APIs should always spell acronyms like words (findId, not findID; + XmlHttpRequest, not XMLHttpRequest)