NPR Visuals' Best Practices

The contents of this repository are released under a Creative Commons CC BY 3.0 License.

Note: This document references the app-template in several places and generally assumes you are using it.

Index

• Project documentation
• Naming things
• Version control
• Servers
• HTML and CSS
• Javascript
• Python

Project documentation

Always ensure the following things are documented in the README:

• Steps to setup the project from a blank slate. (Data loading, etc.)
• Required environment variables. If these are secrets they should also be stored in the team Dropbox.
• Cron jobs that must be installed on the servers. When using the app-template specifying these in the crontab file is sufficient.
• Dependencies that are not part of our standard stack. This includes documenting how to install them. Whenever feasible this documentation should be in the form of fab commands.

Naming things

Naming things (variables, files, classes, etc.) consistently and intuitively is one of the hardest problems in computer science. To make it easier, follow these conventions:

• Always proceed from more general to more specific. For example, widget-skinny is better than skinny-widget.
• Strive for parallelism. If you have a begin() function, then have an end() function (not stop() or done()).
• Group related names with common prefixes, e.g. search_query and search_address.
• Prefer more specific terms to more vague ones. If it's an address call it address, not location.
• When a function operates on a variable, their naming should be consistent. If working with updates then process_updates(), don't process_changes().
• Maintain naming conventions between lists and their iterators: for update in updates, not for record in updates.

Prefer...	to...
create	insert, add, new
update	change, edit
delete	remove, purge
setup	init
make	build, generate
wrapper	wrap
render	draw

(Note: sometimes these words don't mean the same thing, but when they do, prefer the former.)

Version control

• Development of major features should happen on separate branches which periodically merge from master until development of the feature is complete.
• A stable branch should always be present and should merge from master, only when deploying to production.
• Don't store binary files (comps, databases) in the repository.
• If a binary object needs to be shared then store it in Dropbox or on S3. If it is part of the setup process (e.g. a database backup) then use fabric commands to read and write it.
• Never, ever store passwords, keys or credentials in any repository. (Use environment variables instead.)

Servers

• Environment variables belong in /etc/environment. This file should be sourced by cron jobs. (This happens automatically when using run_on_server.sh.)# git

HTML and CSS

See html_and_css.md.

Javascript

See javascript.md.

Python

See python.md.