Skip to content

Best practices and coding conventions for the NPR Visuals team.

Notifications You must be signed in to change notification settings

Lightmatter/bestpractices

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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...
createinsert, add, new
updatechange, edit
deleteremove, purge
setupinit
makebuild, generate
wrapperwrap
renderdraw

(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.

About

Best practices and coding conventions for the NPR Visuals team.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published