code

INN's Best Practices

Based on NPR Visuals' Best Practices with additions for WordPress and PHP.

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

Note: This document references our fork of NPR's 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
• PHP
• WordPress
• Assets

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 be stored in the team's secrets repo.
• 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 vague ones. If it's an address call it address, not location.
• When a function operates on a variable, the 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

The basics

• 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.)

Where we host our code

We use Github and Bitbucket to host our code.

• Github is where we keep code meant for the general public. We will always provide adequate documentation for projects hosted here, monitor issues and pull requests and try to ensure this code is stable and ready for general use.
• We use Bitbucket to house repositories that we deploy from. Code hosted on Bitbucket, while technically open, is usually specific to a particular INN member. Typically, this is not code that anyone outside INN or the member it pertains to would want to use or fork to start their own project, but all of our work is open source so we make this code available and free to use should you find it helpful.

Servers

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

HTML and CSS

See html_and_css.md.

Javascript

See javascript.md.

Python

See python.md.

PHP

See php.md.

WordPress

See wordpress.md.

Assets

See assets.md.