From 7c9b86de9e1ddc6396b80e4e0eb41db9f61d3c98 Mon Sep 17 00:00:00 2001 From: Aaron Boodman Date: Sat, 4 Jan 2014 16:16:20 -0800 Subject: [PATCH] Make some updates to the web application styleguide that have been simmering for a few weeks. Change-Id: I98196f14439b5d6f2c6af53eb1bf3508c6dbc591 --- website/content/docs/web-ui-styleguide | 71 +++++++++++--------------- 1 file changed, 29 insertions(+), 42 deletions(-) diff --git a/website/content/docs/web-ui-styleguide b/website/content/docs/web-ui-styleguide index 7134f63fa..663ef0dc6 100644 --- a/website/content/docs/web-ui-styleguide +++ b/website/content/docs/web-ui-styleguide @@ -1,60 +1,47 @@ -

Web UI Styleguide

+

Web Application Styleguide

+ +

Note: The following statements represent how we think things should be, not how they are. The Web UI is just getting started and doesn't adhere to all of these goals yet. New code should, though. -

Note: The following statements represent how we think -things should be, not how they are. The Web UI is just getting started and -doesn't adhere to all of these goals yet. New code should, though.

Architecture

-

The Camlistore Web UI is an "AJAX"-style web -application that interacts with Camlistore servers just as any other client -would. It speaks the same HTTP APIs as the Android and iOS clients, for example. -We avoid creating APIs that are specific to one client, instead preferring to -generalize functionality such that all current clients and even unknown future -clients can make use of it. +

The Camlistore web application is an "AJAX"-style web app that interacts with Camlistore servers just as any other client would. It speaks the same HTTP APIs as the Android and iOS clients, for example. We avoid creating APIs that are specific to one client, instead preferring to generalize functionality such that all current clients and even unknown future clients can make use of it. + +

The web application is written almost entirely in JavaScript. We make no effort to "degrade gracefully" in the absence of JavaScript or CSS support. -

The Web UI is written almost entirely in JavaScript. We make no effort to -"degrade -gracefully" in the absence of JavaScript or CSS support. We try to minimize -usage of literal HTML markup in the source, as it tends to lead to poor -modularity. We instead prefer to construct DOM trees programmatically.

Paradigm

-

Though we are architected mostly as a "single-page -application", we make extensive use of URLs via -pushState(). -In general every unique view in the application has a URL that can be used to -revisit that view. +

Though we are architected mostly as a "single-page application", we make extensive use of URLs via pushState(). In general every unique view in the application has a URL that can be used to revisit that view. + +

In the same vein, although we are an interactive application, we make appropriate use of web platform primitives where they exist. We use <a> tags for clickable things that navigate, so that browser tools like "Open in new tab" and "Copy link" work as users would expect. Similarly, when we want to display text, we use HTML text rather than <canvas> or <img> tags so that selection and find-in-page work. -

In the same vein, although we are an interactive application, we make -appropriate use of web platform primitives where they exist. We use <a> -tags for clickable things that navigate, so that browser tools like "Open in new -tab" and "Copy link" work as users would expect. Similarly, when we want to -display text, we use HTML text rather than <canvas> or <img> tags -so that selection and find-in-page work.

Stack

-

We use Google Closure, -mainly for its excellent dead-code removal and decent standard library. We -use some Closure UI widgets, but are also happy to bypass the Closure UI layer -and implement our own UI directly on the DOM when that's easier. +

We use Closure as our "standard library". It has a really wide and deep collection of well-designed and implemented utilities. We model our own application logic (e.g., SearchSession) as Closure-style classes. + +

For the UI we are using React because it is awesome. Some older parts of the code use Closure's UI framework; those will be going away. +

Style

-

We follow the Google JavaScript Styleguide and the Closure JSDoc Rules for formatting and so-on. Those of us that use Emacs -install Js2Mode. +

Tabs, not spaces

+

For consistency with Go, and because it makes worrying about minor formatting details like line-wrap style impossible. Some old code still uses spaces. If you are going to be doing significant work on a file that uses spaces, just convert it to tabs in a commit before starting. + +

No max line length

+

It's non-sensical with tabs. Configure your editor to wrap lines nicely, and only insert physical line breaks to separate major thoughts. Sort of where you'd put a period in English text. Look at newer code like server_connection.js for examples. + +

Continuation lines are indented with a single tab

+

Always. No worrying about lining things up vertically with the line above. + +

Type annotations

+

We don't currently using the Closure compiler, and there's some debate about whether we ever will. However, if you're going to have a comment that describes the type of some identifier, you may as well make it rigorous. Use the Closure type annotations for this. + +

Other formatting minutiae

+

Everything else generally follows the Google JavaScript Styleguide. Or you can just look at the surrounding code. +

Compatibility

-

We target the last two stable versions of Desktop Chrome, Firefox, Safari, -IE. We also target the last two stable versions of Safari and Chrome on Android -and iOS tablets. We don't currently target the phone form factor at all, though -it probably sort of works with a lot of zooming and panning. +

We target the last two stable versions of Desktop Chrome, Firefox, Safari, IE. We also target the last two stable versions of Safari and Chrome on Android and iOS tablets.