For new additions or changes to the guide, create a branch and submit a Pull Request. Only add/change 1 style guide rule per Pull Request. The Pull Request serves as a place to discuss and refine the additions/changes.
Use Github Flavoured Markdown.
Each rule should have the following format:
## Rule name
Short summary of the rule to provide context.
### Why?
* list
* of
* benefits
### How?
Instructions with code examples.Use short and descriptive rule names as 2nd level heading:
## Avoid `.ready()`Put a short summary directly after the rule name to provide context. When referencing jQuery API methods, link them to jQuery's docs:
jQuery's [`.ready()`](https://api.jquery.com/ready/) ensures your script is not executed before the DOM is ready. [...]Describe why the rule exists. What purpose does it serve? Bullet lists are often most effective:
### Why?
* Using `.ready()` means scripts have been loaded too early. Therefore defer loading instead.
* Script loading blocks page rendering. Therefore script loading should be defered. Describe how (and how not) to apply the rule:
### How?
Defer script loading by placing scripts just before the closing `</body>` tag or using the [`defer` attribute](https://developer.mozilla.org/en/docs/Web/HTML/Element/script#attr-defer):When using code snippets:
- use
```htmlfor highlighted markup examples. - use
```javascriptfor highlighted script examples. - use
<!-- recommended -->and/* recommended */or<!-- avoid -->and/* avoid */at the start of the snippet to indicate if it's a good or bad practice.
For example:
<!-- recommended: load in tail -->
<body>
...
<script src="path/to/jquery.min.js"></script>
<script>/* DOM is ready, use jQuery directly */</script>
</body><!-- avoid: -->
<head>
...
<script src="path/to/jquery.min.js"></script>
<script>jQuery.ready(function(){ /* ... */ });</script>
<!-- same applies to external script containing `.ready()` -->
</head>Add a ↑ back to Table of Contents link at the end of each rule, so the reader can easily navigate back:
[↑ back to Table of Contents](#table-of-contents)