Ideas On Purpose is a creative company which understands and respects coding as a distinct creative process.
This document defines a loose, common technical baseline for web projects produced at Ideas On Purpose. We aren't interested in telling anyone how to work, but we do ask that a few guidelines be followed to ensure smooth collaboration and efficient maintenance of our projects into the future.
Very few of these rules are mandatory and we're open to discussion.
Technology advances very quickly, especially on the web. This is a living document and we welcome suggestions, criticisms and alternatives. Please share your ideas and help make it easier for all of us to make great work together.
The rules below loosely adhere to common requirement keywords as defined in RFC 2119.
- MUST, REQUIRED
- We need you to do these.
- SHOULD, RECOMMENDED
- Practices we strongly recommend. This could be understood as "strongly prefers". Please let us know if you will be doing something different.
- MAY, OPTIONAL
- We really like these and believe projects and developers will benefit from following them.
IOP’s work is created under strict confidentiality agreements with our clients. Projects under development MUST NOT be publicly accessible. Staging, preview and development environments MUST be password protected.
Images and examples from projects under development MUST NOT be shared to social networks without explicit written permission.
Ideas On Purpose MUST be the author of all code and assets. We're all contributors and will be individually credited where appropriate.
Git is REQUIRED for source code management and version control. Developers will be granted access to a project repository on GitHub.
Code SHOULD be pushed frequently, ideally daily. There's no point in pushing broken or partially implemented commits, but please try to keep updates flowing.
Commits SHOULD be granular. Smaller commits are easier to understand and debug.
Libraries and dependencies SHOULD NOT be committed to the project repository. Repositories SHOULD use a .gitignore file to separate third-party code from our development tree. External resources SHOULD be canonical unless explicitly forked.
Versioned files SHOULD follow the SemVer semantic versioning standard.
SemVer versioned files SHOULD begin at version 0.1.0, incrementing patch and minor as appropriate. When a project is launched, versioned files should be bumped to 1.0.0. (Semver Faq)
Git SHOULD be configured to push tags with commits. Set push.followTags to true in your git config.
Files SHOULD be indented with spaces, NOT tabs.
Files MUST NOT mix tabs and spaces.
Files SHOULD use UTF-8 encoding.
Files SHOULD use Unix (LF) line endings. (Windows developers, set git config --global core.autocrlf true)
Files MUST end with a newline. (ref)
Trailing whitespace SHOULD be removed. (exceptions: Markdown, YAML)
Lines more than 80 characters long SHOULD be avoided. (js, php, python)
Modern tooling makes it easy to deliver clean, appropriately formatted code. Please consider using IOP’s .editorconfig file as a starting point, most of the coding rules in this document are included in that file.
IOP RECOMMENDS the use of linting and code-quality tools like eslint and phpcs.
HTML files MUST start with the HTML 5 doctype: <!DOCTYPE html>
HTML files MUST include the IE Compatibility meta tag as the first meta tag in the <head> section, before any conditional comments. References: 1, 2
<meta http-equiv="X-UA-Compatible" content="IE=Edge">HTML files SHOULD be formatted consistently with two-space (soft) indents.
Deliverable HTML files MUST use the full .html file extension, not .htm.
All asset references MUST be case-sensitive.
OPTIONALLY adhere to Code Guide's HTML recommendations.
OPTIONALLY format HTML files with Prettier.
Image tags MUST include alt-text attributes.
JavaScript source code SHOULD be formatted with Prettier.
JavaScript source code using ES2015+ syntax SHOULD be transpiled with Babel for distribution.
JavaScript code SHOULD run in strict mode, production code SHOULD NOT display errors, warnings or messages in the console.
OPTIONALLY use JSDoc compatible doc blocks.
IOP RECOMMENDS authoring stylesheets with the Sass CSS preprocessor.
Stylesheet source files SHOULD follow the GitHub CSS coding style guide.
Stylesheet source files SHOULD be indented using two-space indents.
OPTIONALLY use our CSScomb dotfile.
OPTIONALLY adhere to Code Guide's CSS recommendations or Idiomatic CSS.
PHP code SHOULD adhere to PSR-1 and PSR-2 style guidelines. WordPress projects MAY choose to use WordPress coding standards instead.
PHP files SHOULD be indented using four-space indents. (PSR-2)
PHP code SHOULD be developed with error_reporting set to E_ALL and SHOULD NOT display any errors or warnings. IOP RECOMMENDS using Xdebug for additional backtraces.
A theme's styles.css file MUST be based on IOP's boilerplate metadata block.
Theme directories MUST be prefixed with iop-. E.g. iop-client-theme.
Namespaced PHP files SHOULD use the ideasonpurpose namespace.
WordPress development servers SHOULD enable WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY.
IOP RECOMMENDS descriptive, self-documenting filenames.
Filenames SHOULD be cased logically and consistently. (eg. file1.jpg & file2.jpg; not File1.JPG & FILE2.jpg)
Filenames containing multiple words SHOULD be joined with dashes (hyphens), not underscores.
Image files SHOULD be descriptively named. (eg. empire-state-building.jpg not bldg-1.jpg)
Public-facing HTML pages MUST include page-specific metadata. IOP’s recommended metadata block assigns page properties for the Open Graph Protocol and Twitter Cards. WordPress projects should use the SEO Framework plugin.
Public-facing projects SHOULD collect analytics data. IOP will provide code snippets on a per-project basis.
Projects MUST use the newest available tracking code snippets, always request fresh snippets. (e.g. Google Analytics)
Third-party tracking code SHOULD NOT be modified, unless explicitly necessary.
This repository contains several dotfiles. Don't miss them just because they're invisible in the Finder.
Interested in working with us? We're hiring!
These coding standards documents were a great towards putting this together, thanks to their authors for making them public.
- @mdo's Code Guide
- Isobar's Front-end Code Standards
- TMW Unlimited's Front-End Dev guidelines
- Google HTML/CSS Style Guide
This work by Ideas On Purpose is licensed under a Creative Commons Attribution 4.0 International License.
An Ideas On Purpose project.