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.
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
crontabfile 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
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-skinnyis better than
- Strive for parallelism. If you have a
begin()function, then have an
- Group related names with common prefixes, e.g.
- Prefer more specific terms to more vague ones. If it's an address call it
- When a function operates on a variable, their naming should be consistent. If working with
- Maintain naming conventions between lists and their iterators:
for update in updates, not
for record in updates.
|create||insert, add, new|
(Note: sometimes these words don't mean the same thing, but when they do, prefer the former.)
- Development of major features should happen on separate branches which periodically merge from
masteruntil development of the feature is complete.
stablebranch 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.)
- Environment variables belong in
/etc/environment. This file should be sourced by cron jobs. (This happens automatically when using
HTML and CSS