Best Practices

Naming

“There are only two hard things in Computer Science: cache invalidation and naming things – Phil Karlton”

As you can spend hours in scheming name patterns, structure and conventions we only advice to follow the BEM principles but using as a separator one dash only and always lowercase format: blockname-elementname.

Automation

We try to make our live as easy as possible. For this reason we implemented Gulp JS as task runner instead of Grunt as we prefer code over configuration. There are some helpful commands available:

  • gulp runs gulp lint browser and watch commands
  • gulp lint lints all JavaScript using .jshintrc and .jscsrc
  • gulp docs generates JavaScript API documentation into static/docs
  • gulp images optimised images within /static/img
  • gulp browser connects to a given server (django) and runs livereload on http://0.0.0.0:3000
  • gulp watch starts a watch command for linting

Bootstrap Plugins

We are implementing the following additional Bootstrap plugins into the setup:

Browsers

In order to display an automated message when JavaScript is disabled or there might be lack of support, we integrated the Outdated Browser script within this boilerplate. Styles and settings are automatically set from within Bootstrap.

Editors

You can use any editor you want, to make your life a bit easier we implemented EditorConfig into the boilerplate’s root .editorconfig.

Icons

We integrated the Font Awesome library in addition of Bootstrap’s Glyphicons icons while disabling the Glyphicons as a default. You can reanable them within the `according settings<https://github.com/aldryn/aldryn-boilerplate-bootstrap3/blob/develop/private/sass/libs/_bootstrap.scss#L14>`_.

Libraries

We are implementing the following standard libraries in addition to the default requirements from Bootstrap:

We implemented Bower to help you manage dependencies. Packages are automatically downloaded into /static/vendor/ but not moved to their appropriate folders. This still requires manual work.

Documentation

We write API documentation using the YUIDoc syntax. For HTML and CSS please refer to the styleguide.

Tests

We currently implemented a basic test framework within static/js/tests using QUnit. YOu can simply run tests using the Gulp command gulp tests.