Style guide

Viz collaborations are smoother when we adopt a consistent code style. Here is the style we have chosen:

Naming conventions

1. Viz.yaml element ids: {super_explicit_name}, e.g., transposed_yahara_geom_mobile. Use and encourage your teammates to use highly informative names.
2. R functions that build viz.yaml elements: {phase}.{step_id}(), e.g., process.transposed_yahara_geom()
3. Other R function names: snake case, e.g., bbox_to_polygon()
4. R variable names: snake case, e.g., county_centroids
5. File names: scripts/process/process.transposed_yahara_geom.R, cache/fetch/watershed_boundaries.Rds
6. CSS classes and IDs: kebab case, e.g., fig-text
7. JavaScript functions and variables: camel case, e.g., playButtonInfo, runDemo

Syntax

1. YAML key-value pairs: avoid quoting keys or values unless necessary for proper parsing.

Organization

1. In JavaScript, use namespacing to put related things together and to keep variables localized.
2. Fetch/process/visualize functions should each produce a single file (at the viz 'location') for the sake of clean dependency management.

Handoffs between stages

The fetch/process/visualization/publish phases are conceptually distinct. Within the constraints of efficiency and practicality, and allowing for exceptions, here is what each phase should produce:

1. Fetch functions should preserve a raw or near-raw data format. Limit any processing to actions you're sure no one will need to revise during the viz sprint, so that downloads can be infrequent.
2. The process phase should bring the data all the way from just-fetched to visualization-ready. As much as possible, say 'yes' to tabular and spatial data manipulation, 'no' to SVG, CSS, and JavaScript. There can be 2+ process phases for a single dataset.
3. Visualization functions should produce static (but interaction-ready) graphics.
4. The publish phase is the ideal place for layout, styling, and interactivity.