Skip to content

Commit 4263bdb

Browse files
mbabkermbabker
committed
Merge pull request joomla#64 from babsgosgens/gh-pages
Added to the HTML coding standards
2 parents b03846c + 45f6d0e commit 4263bdb

File tree

1 file changed

+268
-8
lines changed
  • manual/en-US/coding-standards/chapters

1 file changed

+268
-8
lines changed

‎manual/en-US/coding-standards/chapters/html.md‎

Lines changed: 268 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,62 @@
33
These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, and include items from:
44

55
1. [Google's html styleguide](http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml)
6+
2. [JQuery's HTML Styleguide](http://contribute.jquery.org/style-guide/html/)
7+
3. [Nicolas Ghallager's "Principles of writing consistent, idiomatic HTML"](https://github.com/necolas/idiomatic-html)
8+
4. [Harry Robert's "My HTML/CSS coding style"](http://csswizardry.com/2012/04/my-html-css-coding-style/)
9+
4. [The BBC's Media Standards and Guidelines](http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml)
10+
11+
12+
### Doctype
13+
14+
Always use the minimal, versionless doctype.
15+
16+
```html
17+
<!doctype html>
18+
```
19+
20+
### Language
21+
22+
Always define which language the page is written in.
23+
24+
```html
25+
<html lang="en">
26+
```
27+
28+
### Encoding
29+
Always define the character encoding. The encoding should be defined as early as possible.
30+
Make sure your editor uses UTF-8 as character encoding, without a byte order mark (UTF-8, no BOM).
31+
Do not specify the encoding of style sheets as these assume UTF-8.
32+
33+
```html
34+
<meta charset="utf-8">
35+
```
36+
37+
[More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS](http://www.w3.org/International/tutorials/tutorial-char-enc/)
38+
39+
40+
### Capitalisation
41+
All html should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings). Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness in XHTML.
42+
43+
```html
44+
<!-- Good -->
45+
<img src="joomla.png" alt="Joomla">
46+
47+
<!-- Bad -->
48+
<A HREF="/">Home</A>
49+
```
50+
51+
```html
52+
<!-- Good -->
53+
a {
54+
color: #a3a3a3;
55+
}
56+
57+
<!-- Bad -->
58+
a {
59+
color: #A3A3A3;
60+
}
61+
```
662

763
### Protocol
864

@@ -18,8 +74,12 @@ This prevents mixed content issues and results in minor file size savings.
1874
<link rel="stylesheet" href="http://joomla.org/css/main.css">
1975
```
2076

77+
### Elements and Attributes
78+
79+
Always include html, head, and body tags.
80+
2181
### Type attributes
22-
Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
82+
Do not use type or attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
2383
```html
2484
<!-- Good -->
2585
<link rel="stylesheet" href="//joomla.org/css/main.css">
@@ -28,17 +88,77 @@ Do not use type attributes for style sheets (unless not using CSS) and scripts (
2888
<link rel="stylesheet" href="//joomla.org/css/main.css" type="text/css">
2989
```
3090

31-
### Capitalisation
32-
All html should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings).
91+
### Language attributes
92+
Do not use language attributes on script tags.
93+
```html
94+
<!-- Good -->
95+
<script href="//code.jquery.com/jquery-latest.js">
96+
97+
<!-- Bad -->
98+
<script href="//code.jquery.com/jquery-latest.js" language="javascript">
99+
```
100+
33101
102+
### Attributes
103+
104+
Attribute values should be quoted using double ("") quotes. Optional attributes should be omitted.
34105
```html
35106
<!-- Good -->
36-
<img src="joomla.png" alt="Joomla">
107+
<script src="//code.jquery.com/jquery-latest.js"></script>
108+
<!-- Bad -->
109+
<script src='//code.jquery.com/jquery-latest.js'></script>
110+
```
37111

112+
Use attribute/value pairs for boolean attributes
113+
```html
114+
<!-- Good -->
115+
<input type="checkbox" value="on" checked="checked">
38116
<!-- Bad -->
39-
<A HREF="/">Home</A>
117+
<input type="checkbox" value="on" checked>
118+
```
119+
120+
HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.
121+
122+
1. class
123+
2. id
124+
3. data-*
125+
4. Everything else
126+
```html
127+
<!-- Good -->
128+
<a class="[some-value]" id="[some-value]" data-name="[some-value]" href="[some-value]">Text</a>
129+
<!-- Bad -->
130+
<a href="[some-value]" class="[some-value]" id="[some-value]" data-name="[some-value]">Text</a>
131+
```
132+
133+
Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs:
134+
135+
```html
136+
<a class="[some-value]"
137+
data-action="[some-value]"
138+
data-id="[some-value]"
139+
href="[some-value]">
140+
<span>Text</span>
141+
</a>
142+
```
143+
144+
### Elements
145+
Optional closing tags may not be omitted.
146+
```html
147+
<!-- Good -->
148+
<p>The quick brown fox jumps over the lazy dog.</p>
149+
<!-- Bad -->
150+
<p>The quick brown fox jumps over the lazy dog.
151+
```
152+
153+
Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.
154+
```html
155+
<!-- Good -->
156+
<img src="//images/logo.png" alt="">
157+
<!-- Bad -->
158+
<img src="//images/logo.png" alt="" />
40159
```
41160

161+
42162
### Formatting
43163
Use a new line for every block, list, or table element, and indent every such child element.
44164

@@ -51,13 +171,122 @@ Use a new line for every block, list, or table element, and indent every such ch
51171
</ul>
52172
</div>
53173

54-
<!-- Bad - ul is a block element -->
174+
<!-- Bad -->
55175
<div><ul>
56176
<li>Home</li>
57177
<li>Blog</li>
58178
</ul></div>
59179
```
60180

181+
We prefer readability over file-size savings when it comes to maintaining existing files. Plenty of whitespace is encouraged. Use whitespace to visually separate groups of related markup and to improve the readability and maintainability of your HTML. Use two empty lines between larger blocks, and use a single empty line between child blocks of larger blocks. Be consistent. (If you are worried about your document's size, spaces (as well as repeated use of the same strings - for instance class names) are excellent candidates for compression. Also, you may use a markup minifier to decrease your document's file size.)
182+
183+
Keep line-length to a sensible maximum, e.g., 80 columns.
184+
185+
Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.
186+
187+
```html
188+
<blockquote>
189+
<p><em>Space</em>, the final frontier.</p>
190+
</blockquote>
191+
192+
193+
<ul>
194+
<li>Moe</li>
195+
<li>Larry</li>
196+
<li>Curly</li>
197+
</ul>
198+
199+
200+
<table>
201+
<thead>
202+
<tr>
203+
<th scope="col">Income</th>
204+
<th scope="col">Taxes</th>
205+
</tr>
206+
<tbody>
207+
<tr>
208+
<td>$ 5.00</td>
209+
<td>$ 4.50</td>
210+
</tr>
211+
</table>
212+
```
213+
214+
### Indentation
215+
Don't indent inside html, body, script, or style. Indent inside head and all other elements.
216+
Indent by four spaces at a time. Don’t use tabs or mix tabs and spaces for indentation.
217+
218+
219+
```html
220+
<!-- Good -->
221+
<!doctype html>
222+
<html lang="en">
223+
<head>
224+
<meta charset="utf-8">
225+
<title>Sample Page</title>
226+
227+
<link rel="stylesheet" href="/style.css">
228+
<style>
229+
body {
230+
font-size: 100em;
231+
}
232+
</style>
233+
234+
<script src="/jquery.js"></script>
235+
<script>
236+
$(function() {
237+
$( "p" ).text( $.fn.jquery );
238+
});
239+
</script>
240+
</head>
241+
<body>
242+
243+
<p>Joomla! is awesome!<p>
244+
245+
</body>
246+
</html>
247+
```
248+
249+
### Trailing Whitespace
250+
Remove trailing white spaces. Trailing white spaces are unnecessary and can complicate diffs.
251+
252+
```html
253+
<!-- Good -->
254+
<p>Yes please.</p>
255+
256+
<!-- Bad -->
257+
<p>No, thank you. </p>
258+
```
259+
260+
261+
### Entity References
262+
Do not use entity references. There is no need to use entity references like &mdash;, &rdquo;, or &#x263a;, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
263+
264+
The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).
265+
```html
266+
<!-- Good -->
267+
<p>The currency symbol for the Euro is “€”.</p>
268+
269+
<!-- Bad -->
270+
<p>The currency symbol for the Euro is &ldquo;&eur;&rdquo;.</p>
271+
```
272+
273+
### Inline CSS
274+
275+
Inline CSS must be avoided. When altering states using JavaScript, use CSS to define your states, and only use onobtrusive JavaScript to alter class names whenever possible.
276+
```html
277+
<!-- Good -->
278+
<a class="is-link-disabled" href="//index.php">Home</a>
279+
280+
<!-- Bad -->
281+
<a href="//index.php" style="text-decoration: line-through;">Home</a>
282+
```
283+
284+
@todo more meaningful example.
285+
286+
### Style Attributes
287+
You should not use border, align, valign, or clear attributes. Avoid use of style attributes, except where using syndicated content or internal syndicating systems.
288+
289+
61290
### Semantics
62291
Use HTML according to its purpose. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.
63292

@@ -66,10 +295,34 @@ Using HTML according to its purpose is important for accessibility, reuse, and c
66295
<!-- Good -->
67296
<a href="subscriptions/">View subscriptions</a>
68297

69-
<!-- Bad - ul is a block element -->
298+
<!-- Bad -->
70299
<div onclick="goToSubscriptions();">View subscriptions</div>
71300
```
72301

302+
303+
304+
### Markup
305+
306+
#### Image Tags
307+
Image elements (<img>) must have an alt attribute. Height and width attributes are optional and may be omitted.
308+
309+
310+
@todo add examples from here http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml
311+
312+
### Comments
313+
@todo: comment styles in JS, CSS, HTML
314+
For more complex blocks of HTML, it may be useful to add a comment to the closing tag:
315+
```html
316+
<div class="parent">
317+
318+
<div class="child">
319+
</div><!-- /child -->
320+
321+
</div><!-- /parent -->
322+
```
323+
324+
325+
73326
### Mark todos
74327
Highlight todos by using the keyword TODO, eg:
75328

@@ -79,4 +332,11 @@ Highlight todos by using the keyword TODO, eg:
79332
<li>Home</li>
80333
<li>Blog</li>
81334
</ul>
82-
```
335+
```
336+
337+
338+
339+
### Markup validation tools
340+
@todo: list various testing tools:
341+
* http://validator.w3.org/nu/
342+
* http://csslint.net/

0 commit comments

Comments
 (0)