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.
Architecture
The Perkeep web application is an “AJAX”-style web app that interacts with Perkeep 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.
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.
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 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
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.