├── python.md ├── assets.md ├── html_and_css.md ├── git.md ├── README.md └── javascript.md /python.md: -------------------------------------------------------------------------------- 1 | ## Best Practices for Python 2 | 3 | ### Baseline 4 | 5 | * [PEP8](http://www.python.org/dev/peps/pep-0008/). 6 | * [Django Coding Style](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/). 7 | * **Use single-quotes for strings.** 8 | 9 | ### Libraries 10 | 11 | For consistency, prefer the following libraries to others that perform the same tasks: 12 | 13 | * [Fabric](http://docs.fabfile.org/) for project tasks 14 | * [Flask](http://flask.pocoo.org/) for light web apps **or** [Django](https://www.djangoproject.com/) for heavy web apps 15 | * [boto](https://github.com/boto/boto) for accessing AWS programmatically 16 | * [pytz](http://pytz.sourceforge.net/) for manipulating timezones 17 | * [psycopg2](http://www.initd.org/psycopg/) for accessing Postgres 18 | * [lxml](http://lxml.de/) for XML/DOM manipulation 19 | * [Requests](http://docs.python-requests.org/en/latest/) for working over HTTP 20 | 21 | ### Specifics 22 | 23 | * When testing for nulls, always use ``if foo is None`` rather than ``if !foo`` so ``foo == 0`` does not cause bugs. 24 | * Always initialize and store datetimes in the UTC timezone. Never use naive datetimes for any reason. 25 | * Always use ``with`` when accessing resources that need to be closed. 26 | * Always access blocking resources (files, databases) as little as possible. 27 | * When accessing a dictionary element that may not exist, use ``get()``. For example, ``os.environ.get('DEPLOYMENT_TARGET', None)``. 28 | * Project settings that will be used by both fabric and other code should be isolated in ``app_config.py``. ``fabfile.py`` and Django's ``settings.py`` should import from this file to prevent duplication. 29 | * Imports should be organized into three blocks: stdlib modules, third-party modules and our own modules. Each group should be alphabetized. 30 | * Avoid ``from foo import *``. It is the mindkiller. 31 | * Functions that are de facto "private" (only called within a module or only called within a class) should be prefixed with a single `_`, e.g. `_slugify`. 32 | 33 | ### Flask 34 | 35 | * All views should return with ``make_response``. 36 | -------------------------------------------------------------------------------- /assets.md: -------------------------------------------------------------------------------- 1 | ## Best Practices for Assets 2 | 3 | * File extensions should always be lowercase. 4 | * When possible, lazy-load assets. 5 | * Files can be checked into source control if they're under 5MB, and don't have a method of getting them through an automated process. Alternatively, provide a build task that will create/download those assets that are larger or depend on data sources (such as the covers for the book concierge). 6 | 7 | ### Audio 8 | 9 | * Music should be encoded as 128bps CBR Stereo: 10 | * MP3: `lame -m s -b 128 input.wav output.mp3` 11 | * Voice should be encoded as 96bps CBR Mono: 12 | * MP3: `lame -m m -b 96 input.wav output.mp3` 13 | 14 | ### Photo 15 | 16 | You can resize images on the command line with ImageMagick. This script (borrowed from the [Ellicott City](https://github.com/nprapps/ellicott-city#snippets) project) will look at all the JPGs in a folder and saved the resized versions in a `resized` folder: 17 | 18 | ``` 19 | for f in *.jpg; do magick $f -quality 75 -resize 1600x1200\> -strip -sampling-factor 4:2:0 -define jpeg:dct-method=float -interlace Plane resized/$f; done 20 | ``` 21 | 22 | ### Video 23 | 24 | Video encoding depends on the role of the video in a project--ambient video (such as animated backdrops) should be much smaller, because the user doesn't have a choice about playback. On-demand video can be much larger--but consider uploading it to a hosting service like YouTube instead of manually encoding, since those will automatically size and compress for different screen sizes and bandwidth requirements. 25 | 26 | When encoding for a browser, use FFMPEG to output as MP4. The command for doing this in a way that will cooperate with all platforms is somewhat verbose: 27 | 28 | ```sh 29 | ffmpeg \ 30 | -i inputfile \ 31 | -ss 0 -t 5 \ 32 | -an \ 33 | -vcodec libx264 \ 34 | -preset veryslow \ 35 | -strict -2 \ 36 | -pix_fmt yuv420p \ 37 | -crf 21 \ 38 | -vf scale=800:-1 \ 39 | outputfile.mp4 40 | ``` 41 | 42 | Note that the order of arguments is important. Some of these parameters may be tweakable depending on what your video is meant to accomplish. 43 | 44 | * `-an` - Removes audio for autoplaying video in modern browsers 45 | * `-ss X -t Y` - Extracts Y seconds, starting at X 46 | * `-vf scale=ZZZ:-1` - Resizes the video to ZZZ across, maintaining its current aspect ratio. 47 | * `-crf X` - Sets the quality of the compression to X, where 0 is lossless and 51 is gibberish. 21 is a good starting place. 48 | 49 | -------------------------------------------------------------------------------- /html_and_css.md: -------------------------------------------------------------------------------- 1 | ## Best Practices for HTML and CSS 2 | 3 | 4 | ### HTML 5 | 6 | * Element IDs and class names should always be `lowercase-with-dashes`. 7 | * Put modals and JST templates in their own files. In the app-template these belong in the `templates` and `jst` directories, respectively. When this isn't feasible, put modals in the page footer first, followed by inline javascript templates. 8 | * Attributes should be double-quoted, even in cases where it will parse without quotes. 9 | * Images should always have an "alt" attribute that contains a screenreader-friendly description of their contents. If the image is only for presentational purposes, set the attribute to an empty string so that it will be ignored. 10 | * Follow [WAI-ARIA best practices](https://www.w3.org/TR/wai-aria-practices/) for interactive elements, such as buttons, menus, or tabs. Test all HTML in a screenreader with this as a guide. 11 | * Use semantic HTML for the appropriate purposes. 12 | - Never use a `
` for a clickable element. If the element updates the page, use a `