HTML Standards & Guidelines

HTML5 AND CSS CODING CONVENTIONS (updated: 11/27/12)

INTRODUCTION:

This document describes the HTML5 and CSS3 coding style that you must use for this class. Most of these guidelines are widely accepted. However, alternative guidelines do exist in many areas. You must follow the guidelines in this document so that you will learn to code consistently and I will be able to grade consistently.

While reading the following sections, refer to the sample web page and its associated sample style sheet at the bottom of this document. Mimic the style used in those two pages. Before turning in a web page assignment, please review all the details of this document to make sure that you are using proper style. This will save you points and it will save me countless hours of grading. Please be kind. Thank you.

I have searched on the Internet for a satisfactory HTML coding-conventions document. Unfortunately, there is no universally agreed-upon document. In conducting my search, I've sifted through and evaluated many HTML coding practices. This document attempts to present the best HTML coding practices that conform to the HTML5 standard. Here are some of the sources I've used for this document:  W3C’s Doctypes and markup styles “Note for teachers” (http://www.w3.org/community/webed/wiki/Doctypes_and_markup_styles#A_note_for_teachers )  Google HTML/CSS Style Guide (http://google- styleguide.googlecode.com/svn/trunk/htmlcssguide.xml)  Preferred Syntax Style for HTML5 Markup (http://www.impressivewebs.com/html5-syntax- style/)

This document addresses only HTML coding style issues. It does not address user-interface design issues such as:  layout  color aesthetics  navigability  content  accessibility

FILES:

HTML file names should end in .html (not .htm).

Rationale: Using the full HTML acronym is more descriptive.

W3C's VALIDATION SERVICE: 2.

Validate every web page and every external style sheet by using W3C's validation services. The HTML and CSS validation services, respectively, are found here: http://validator.w3.org/ http://jigsaw.w3.org/css-validator/

Rationale: Cross-browser compatibility.

COMMENTS:

1. Short comments should be written on one line. Insert a space after the "". For example:

http://www.park.edu/compsci

2. Comments that require more than one line should use block-style indented text. For example:

GENERAL:

1. Include closing tags for all container-type elements. For example:

Park University, founded in 1625 by the Franciscan Monks, quickly gained national attention for its efforts in the fields of Alchemy and Computer Science.

This is not required by the HTML5 standard, but in the interest of consistency and readability, you should do it.

2. Use lowercase characters for all tags and attributes.

3. Enclose all attribute values in double quotes.

4. Because the name attribute can be used to identify elements in JavaScript, and JavaScript coding conventions suggests using camel case for multi-word variable names, use camel case for values for the name attribute. 3.

5. Do not use spaces around the equal sign when specifying an attribute value pair. For example:

Rationale: Group related entities together so that tag components are compartmentalized.

6. Blank lines:

 Insert blank lines to separate large logical chunks of code.

 Insert a blank line between the head and body sections.

 Do not insert a blank line unless there's a reason to do so.

7. Indentations:

 Indentations should use two spaces.

8. For void elements, you may optionally insert a blank space and slash ( /) at the left of the closing >, like this:

However, I recommend no blank space and no slash. Whichever convention you choose, be consistent.

9. Avoid long lines:

 Within an IDE (like Visual Studio), it is annoying for programmers to have to scroll right in order to see the end of a line of code. Also, if you paste your code to a word processing document, it is annoying to see line wrap. To avoid these problems, split up long lines by pressing enter at natural breaking points. As a rule of thumb, try to avoid lines that require more than 80 characters (including blank spaces). Definitely avoid lines that require more than 100 characters (including blank spaces). For a definitive rule on line length, ask your teacher or manager.

TOP OF THE DOCUMENT:

1. Include the following line at the top of your HTML5 documents:

This will tell the browser to use the HTML5 version of HTML (because other versions of HTML use slightly different forms of the doctype tag).

Although most examples on the W3C and Google sites use all uppercase for the doctype tag (), the W3C and Google sites do not explicitly recommend uppercase. Since lowercase is legal for the doctype tag, and it’s the norm for all other tags, in the interest of consistency, you should use lowercase for doctype. 4.

HEAD CONTAINER:

The following items should be included in the order shown.

1. Include a meaningful title element on each page. For example:

Dean Family

Rationale: Helps search engine functionality.

2. For grading purposes, I need to know your name, so you are required to include an author meta element. For example:

3. As an option, to help search engines find your pages, you may also want to include description and keywords meta elements. For example:

4. As an option, to prevent attacks on client computers that use older browsers, you may also want to include the following charset meta element:

5. For external style sheets, use the link element. For example:

BODY CONTAINER:

1. Insert a blank line between large (≥ 5 lines?) block-level elements:

 Block-level elements are not formally defined in the HTML5 standard, but they are informally recognized as the elements that are in HTML5’s flow category, but not in HTML5’s phrasing category. By default, each block-level element begins on a line by itself and ends on a line by itself. This is in contrast to inline elements, which appear within the flow of surrounding text.  HTML5’s block-level elements are: address, article, aside, blockquote, canvas, details, div, dl, fieldset, figure, footer, form, h1, h2, …, h6, header, hgroup, hr, menu, nav, ol, p, pre, section, table, ul  Do not insert blank lines between short, related block-level elements. In the example below, h1 and h2 are short and related so there is no blank line separator. On the other hand, the heading elements should be separated from the p element with a blank line.

Doesn't every child dream of having his/her very own pet rat? With the "One Child, One Rat" program, that dream can become a reality.

2. Indentations:

 Most reputable HTML5 code (code that comes from reference textbooks and reference websites) uses indentations for nested block-level elements, lists, and tables. Consequently, I require indentations for those entities. Some reputable HTML5 code uses indentations for block-level container content and line continuations, but those indentation practices vary widely. For readability and consistency within our class, I require indentations for block-level container content and line continuations.

 Nested block-level elements:

○ Insert a newline with an indent prior to every block-level start tag that is logically inside of a block-level element.

○ In the example below, the h1 block-level tag is indented because it is inside of the header block-level element. The p tag is not indented because it is not inside of another block-level element. The strong tag does not require a newline or indent because it is an inline element, not a block-level element.

Welcome to Parkville – Party Town, USA.

 Lists and tables:

○ Insert a newline with an indent prior to every list element that is logically inside of another list element.

○ Insert a newline with an indent prior to every table element that is logically inside of another table element.

○ See the Lists and Tables sections below for more details.

 Block-level container content:

○ If a block-level container cannot fit on one line, insert a newline with an indent after the block-level start tag. Unindent the end tag. For example:

Parkville's pristine white sandy beaches along the Missouri River attract vacationers from the world over. -Parkville Mayor, Jay Norman. After sun-worshipping all day, relax and enjoy Parkville's scintillating nightlife. Pirate Grounds is always a big hit with the singles!

 Line continuation: 6.

○ If a tag cannot fit on one line, insert newlines at logical breaking points. The following examples illustrate what constitutes a logical breaking point. In the examples, the a tag cannot fit on one line so newline insertions are required. In the "bad" example, newlines are inserted after "href=" and "onmouseover=." Those are poor breaking points because the href and onmouseover assignments are broken up. In the "good" example, newlines are inserted after "web site –" and "return true;". Those are good breaking points because they help prevent the href, onmouseover, and onmouseout assignments from being broken up.

bad: good:

For additional information on our ICS For additional information on our ICS program, program, check out this web site - onclick="return confirm('Are you sure?');"> http://www.park.edu/ics http://www.park.edu/ics

○ If a tag cannot fit on one line, the first continuation line should be indented. If more than one continuation line is required for a particular tag, the second, third, etc. continuation lines should be aligned with the first continuation line.

In the right-side example above, the a tag uses the recommended indentation.

3. Lists:

 The ol, ul, and dl list elements are recognized as block-level elements. The li element could also be categorized as a block-level element, as it mimics the other block-level elements in terms of newlines and indentations. In applying the above block-level indentation rules to the ol, ul, dl, and li elements, you should indent each of those elements as follows:

 As shown above, when embedding a list inside of a list, the outer list's end tag must be placed below the embedded list. 7.

4. Tables:

 The table element is recognized to be a block-level element. The thead, tbody, and tr elements could also be categorized as block-level elements, as they mimic the other block-level elements in terms of newlines and indentations.. In applying the above block-level indentation rules to the table, thead, tbody, and tr elements, you should indent each of those elements as follows:

 When embedding a table inside of a table, apply the table indentation rules recursively. I'll let you work out an example on your own. 

5. Images and colors:

 Include width and height attributes for all img elements.

Rationale: Faster page loading.

 Include the alt attribute for all img elements. Use alt="" for decorative images.

Rationale: Alternate text serves as content when an image cannot be rendered or viewed normally.

 Do not use animated gifs or use them sparingly.

Rationale: Animations are annoying.

6. Character references:

 In the interest of readability, if there's a choice, use regular characters and not character references. Here's when it's appropriate to use a character reference:

○ Use a character reference to display a character that's not on the keyboard. 8.

○ Use a character reference to display a character that would normally have a special meaning in HTML:

<, >, &

" and ', but only when they are inside of an attribute value string

○ Use an character reference if you need to:

Display a blank space without allowing a line break (to ensure that a group of words will be displayed on the same line).

Display multiple blank spaces without allowing whitespace collapsing.

 According to http://www.w3.org/TR/html4/charset.html, HTML character references fall into two categories – character entity references and numeric character references. Character entity references use the format – &name;. Numeric character references use the format – &#unicode- value;. Some symbols are represented by both a character entity reference and also a numeric character reference. For example, the less than symbol is represented by < and also by <. If a symbol is represented by both types of character references, you should use the character entity reference version because character entity references are more understandable. Some symbols are represented only by a numeric character reference and not a character entity reference. Because numeric character references are rather cryptic, you should provide a comment whenever you use a numeric character reference for the first time in a web page.

7. Miscellaneous:

 Plain text should not appear immediately within the html container, the head container, or the body container. Plain text should appear only within container elements that are within the body element. “Plain text” refers to characters that are not within a tag’s < and > symbols.

This is not required by the HTML5 standard, but it enables the page content to be described more fully, so it can be manipulated by CSS and JavaScript.

 Usually (but not always), a text element should be put inside a block-level element, but not directly inside the body container.

Rationale: Usually, text elements appear within the flow of surrounding text. If that’s the case, then, in applying the plain text rule above, the text element and its surrounding text should be put inside a block-level element.

 Do not specify precise sizes for text font. Instead, use header tags (h1, h2, etc.) or use style sheets with font-size values such as small, large, smaller, larger, 125%, etc.

Rationale: Using precise values is misleading since the size may still be different on different browsers.

KEEP CONTENT AND PRESENTATION SEPARATE: 9.

1. Use HTML elements for content and CSS for presentation.

2. Since the b, i, and u elements implement presentational semantics, do not use them. Instead, use other elements that properly describe the text or use the following CSS property-value pairs:

font-weight: bold font-style: italic text-decoration: underline

STYLE SHEETS:

1. In an embedded style element and also in a link element to an external style sheet, include a type attribute with a value of "text/css". Here are two separate examples:

 CSS is the default type for a style element, so, functionally, there’s no difference between including and omitting type="text/css". However, to help with self-documentation, include it.

2. Comments:

 You should supply comments within your CSS code for any rules that are non-intuitive.  If the comment is short, insert it to the right of the rule that the comment applies to.  If the comment is long, insert it immediately above the rule(s) that the comment applies to. To give the comment more prominence, insert a blank line above the comment.  For grading purposes, I need to know your name, so for external style sheets, you are required to include your name in a comment at the top of the external style-sheet file. For example:

/* John Dean */

3. Surround logical groups of rules with blank lines.

4. Short rules:

 If you have just one property-value pair, or you have just a few property-value pairs, and none of the values are font-family lists, then you may put them on one line, with a space following each interior semicolon, like this:

.opening-statement {font-style: italic; color: blue;} .closing-statement {font-family: "Times New Roman", Times, serif;}

 With one-line rules, insert a blank space before the opening brace. There should be no blank spaces to the right of the opening brace and to the left of the closing brace.

5. Long rules: 10.

 If you have a rule with a long heading and/or lots of property-value pairs, use block-style notation. For example:

body { background-color: white; color: black; a:visited: green; a:link: red; font-family: "Arial Black", Helvetica, sans-serif; }

 With block-style notation, place the opening brace on the same line as the selector, separated from the selector by one space.

6. Insert a blank space after a CSS property's colon. There should be no blank space before the colon.

7. For a font family list, insert a space after each comma.

8. Use hyphens to separate multi-word class values and multi-word id values.

9. Include a semicolon after the last property-value pair.

 Although CSS standards allow you to omit the semicolon after the last property-value pair, you should include it. That way, if another rule is added later on, there will be less likelihood of accidentally forgetting the semicolon to separate the prior property-value pair from the new one.

10. Unless there’s a special reason, do not use the blink value for the text-decoration property. 11.

SAMPLE WEB PAGE

Dean Family

As usual, not much has happened to us this year. We just forge ahead with the usual mundane, ho-hum stuff. Let's see ... our dog Sophie is doing fine, Stacy's still working at Olathe Medical Center, we now have progeny, etc.

OK, I guess I'll start with the progeny. Her name is Jordan Alexandria Dean. Born one month early, March 5, medium height, medium build. She's doing great. As babies go, she's a keeper. Our parents tell us she's cute as a button. She smiles a lot, sits well, and has a very mature palette. Her hobbies include playing with Sophie, eating, burping, and curling up in front of a fire with a good book. A very likable kid.

Updated information:

Eventually, we'd like to add a family tree to this web page. If anyone in the family is interested in working on that project, please feel free to get started by evaluating these family tree tools:

Updated August 18, 2012

SAMPLE EXTERNAL STYLE SHEET (referenced as style.css in sample web page, above)

/* John Dean */ body {background-color: white; color: black;} nav {text-align: center;}

/* Apply special formatting to the links at the top. */ nav a, .current-tab { color: white; font-family: Arial, Helvetica, sans-serif; } nav a {background-color: #666666;} nav a:hover {background-color: blue;} .current-tab {background-color: green;} h1 {text-align: center;} hr { background-color: red; height: 1px; /* hr color works only if height is specified */ }

.date { color:red; font-family: "Trebuchet MS", Helvetica, sans-serif; font-size: smaller; }

HTML Standards & Guidelines

Our Furry Friend

The Common House Rat

Paradise in Parkville!

Dean Family

Dumb table
A	B
one	two
three	four