NPR Visuals' Best Practices
The contents of this repository are released under a Creative Commons CC BY 3.0 License.
Index
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 thanskinny-widget
. - Strive for parallelism. If you have a
begin()
function, then have anend()
function (notstop()
ordone()
). - Group related names with common prefixes, e.g.
search_query
andsearch_address
. - Prefer more specific terms to more vague ones. If it's an address call it
address
, notlocation
. - When a function operates on a variable, their naming should be consistent. If working with
updates
thenprocess_updates()
, don'tprocess_changes()
. - Maintain naming conventions between lists and their iterators:
for update in updates
, notfor 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. - Never, ever store passwords, keys or credentials in any repository. (Use environment variables instead.)
See git.md.
Servers
- Environment variables belong in
/etc/environment
. This file should be sourced by cron jobs. (This happens automatically when usingrun_on_server.sh
.)# git
HTML and CSS
See html_and_css.md.
Javascript
See javascript.md.
Python
See python.md.
Assets
See assets.md.