Coding Standards for SYST10049

This document contains a few of the common standards and conventions used in web development and web programming. You should follow these standards for this course. Marks are allotted for following proper coding standards/style/conventions on every assignment.

A more extensive list and description of web programming standards is available at the Google HTML/CSS Style Guide

Naming Conventions for Identifiers

Naming conventions for identifiers in HTML (e.g. id or name attribute values), CSS (e.g. class/id names), JavaScript, and PHP should be followed to improve readability. Some languages include special prefixes that are prepended to variable and object names to identify the types of data or object.

Regardless of language and type of identifier, all identifiers must be self-documenting (you can tell exactly what the identifier is for by reading its name). For example, custFirstName is clearly a customer's first name and validateEmail obviously performs data validation on an email address. Names like single letters (x, c, etc), or names that are meaningless (count1, temp, f23) should not be used (one exception is that we often use a single letter such as i in a for-loop).

The following table outlines naming conventions for various types of identifers in the web programming technologies covered in this course:

	Identifier type
Language	class/id	variable	method/function	class (oop)	constants
HTML	all lower-case, hyphens to separate words	n/a	n/a	n/a	n/a
CSS	all lower-case, hyphens to separate words	n/a	n/a	n/a	n/a

Identifier type

Language

class/id

variable

method/function

class (oop)

constants

HTML

all lower-case, hyphens to separate words

n/a

CSS

all lower-case, hyphens to separate words

n/a

Indentation and Spacing

Indentation and spacing keeps code readable, especially when there are nested structures involved. For example, if you have a series of <section< tags and each has a set of <div> tags, proper indentation will make it easier to read and edit your document. Similarly, a JavaScript or PHP program with nested if's and loops is easier to follow and maintain when it's indented properly.

Size of Indents

The size of indents varies. The table below outlines the size of indents in the various web technologies used in this course:

Language	Indent Size (# of spaces)
HTML	2
CSS	2

Language

Indent Size (# of spaces)

HTML

CSS

Note that indents should always be actual spaces, not tabs. Since programmers rarely actually type spaces when indenting because it's a huge pain when you have nested structures, most good IDEs/editors have an option to convert tabs to actual spaces. The reason for using actual spaces is so that tabs cause hassles when applying patches or updates to your program or when using tools that allow you to view/modify/revert historical modifications to your application.

When nesting structures, always add one indentation level per nesting leve. Examples:

HTML Example:

<body>
  <section>
    <div>Some content.</div>
  </section>
        
  <section>
    <div>Some content.</div>
    <div>Some more content.</div>
  </section>
</body>

Spacing

There are two categories of spacing: blank lines in code and blank space in code statements.

In general, there should be a blank line in the following circumstances:

Between groups of logically similar statements.
Above and below a method/function header.
Between blocks of code (code inside a set of braces).
Above a comment.

Blank lines should not appear in the following circumstances:

Between a comment and the statement(s) the comment is documenting.
Between the first line and second/subsequent lines of a single, long wrapped statement.

In general, a blank space should appear in a code statement in the following circumstances:

Around an operator (such as ==, =, +, /, new). An exception that many programmers use is around the concatenation operator in PHP
(e.g. "Hello, ".userName)
After a comma.
Before an opening brace if there's something in front of the brace. For example, in a CSS rule, there should be a space between the last selector and the opening brace.

Blank spaces should not appear in the following circumstances:

Between a function/method name and the opening parenthesis.
After any opening parenthesis and its contents or before any closing parenthesis and its content.
In the middle of any identifier.
In front of a comma.

Additionally, each language covered in this course has some specific rules regarding blank lines and spaces:

Language	Blank Lines	Blank Space
HTML	- as with any language, you should make sure there are blank lines between related groups of statements; generally before and after block elements, after the opening BODY element, and above the closing BODY element	- there should never be a blank space around the assignment operator when assigning a value to an attribute e.g. <a href="images/pic.png" alt="a picture"> is correct.
CSS	- between rules, i.e there should be a blank line after the closing brace of a rule and the start of the next rule	- after the colon that follows a selector e.g. font-size:150%; is incorrect because there should be a space after the :

Language

Blank Lines

Blank Space

HTML

- as with any language, you should make sure there are blank lines between related groups of statements; generally before and after block elements, after the opening BODY element, and above the closing BODY element

- there should never be a blank space around the assignment operator when assigning a value to an attribute e.g. <a href="images/pic.png" alt="a picture"> is correct.

CSS

- between rules, i.e there should be a blank line after the closing brace of a rule and the start of the next rule

- after the colon that follows a selector e.g. font-size:150%; is incorrect because there should be a space after the :

Line Length

Industry standard for most languages state that the length of a line should not exceed 80 characters.

If a statement is longer than 80 characters, break that statement up over multiple lines. The second and subsequent lines must be indented.

If a language supports end-of-line comments, use them only if the total number of characters in the line, including the comment, is 80 characters or less. If your comment makes the line longer than 80 characters, place the comment above the statement, instead.

Most editors allow to to add a margin marker at a specific column to help you see where the 80 character mark is.

Breaking Long Lines

When breaking a long statement into multiple lines of code, you must always indent the second and subsequent lines. See the Indentation and Spacing standards for information on the size of an indent for each language covered in this course.

In most languages there are rules regarding where you can place a hard-return in a long line. In general, the following rules apply:

After a comma.
Before an operator (i.e. operators should be at the beginning of the next line).
DO NOT break a line in the middle of a string literal. Close the string's quotes when you're ready to break the line, then start the new line with the concatenation operator and continue with the string literal. Here's an example using JavaScript:
document.write("<p>This is a long string literal that is "
    + "being displayed over multiple lines of code. This "
    + "is the proper way to break a long line in the middle of "
    + "a string literal.</p>);

Braces

Braces are used in CSS blocks. In CSS, a block defines a style rule.

A left brace (or opening brace) { starts a block and a right brace (or closing brace) } ends a block.

Examples of a block that defines a style for level-2 headings:

h2 {
  font: bold 1.3em sans-serif;
  color: #039;
  border-bottom: 1px solid #039;
}

Brace Style

Brace style defines where you decide to put the opening brace of a block.

CSS always uses end-of-line brace style. You might be familiar with 2 brace styles if you've programmed in any language that uses blocks:

Next-Line Style: places the opening brace on the next line:
```
div
{
   // .... blah blah
}
```
End-of-Line Style: places the brace at the end of the line:
```
div {
   // .... blah blah
}
```

Important! CSS always uses end-of-line brace style!!

Documentation

Documentation should be concise, complete, and written in your own words. Use proper spelling!! There's nothing less professional in your code than bad spelling in your documentation! :P

DO NOT document the ends of long lines like this:

<div class="import"><span class="w3-tag sher-orange w3-right">Important!</span><br>Content Here</div> <!-- box for important information -->

Those kinds of statements are almost impossible to read in any standard editor!

It's better to place the comment above the line, like this:

<!-- box for important information -->
<div class="import"><span class="w3-tag sher-orange w3-right">Important!</span>
<br>Content Here</div>

Document each statement or related groups of statements by describing what they're doing and how it applies to the layout of your document.

Examples

An HTML Example:

<!-- header section of page -->
<header>
  <h1>SPCA Emergency Personnel</h1>

  <h2>Log In to Handle Calls</h2>

  <img class="header-img" src="images/spcaHeader.png" alt="Hamilton SPCA Header">
</header>

<!-- login form that validates inputs on submit -->
<form action="login.php" method="post" name="loginForm" 
         id="login-form" onsubmit="validate(this);">

  <!-- login and user name controls -->
  <p>
    <label for="txtUser">User Name: </label>
    <input type="text" id="txtUser" name="txtUser">
  </p>

  <p>
    <label for="txtPass"></label>
    <input type="password" id="txtPass" name="txtPass">
  </p>

  <!-- submit and reset buttons -->
  <p>
    <input type="submit"> 
    <input type="reset">
  </p>
</form>

<!-- footer section of page -->
<footer>
  <div class="copyright">
    <!-- display copyright notice from script -->
    <script type="text/javascript" src="js/copyright.js"></script>
  </div>
</footer>

A CSS Example

/* Styles for the entire page */
body {
  font-family: Arial, sans-serif;
  margin: 10px;
  padding: 5px;
}
      
/* Selectors for game objects: */

/* The whole game board */
board {  
  border: 1px solid navy;
  padding: 2px;
}

/* Game board cells */
cell {
  border: 1px dashed navy;
  padding: 3px;
}

HTML Standards

In addition to the general standards and conventions already mentioned, the following apply to HTML and should be used in all submissions in this course:

All HTML should be valid.
All elements, attributes, and attribute values must be in lower-case (except DOCTYPE).
Attribute values are always enclosed in double-quotes (unless the code is inside a js or php string, in which case it's easier to use single-quotes e.g. document.write("<img src='images/pic.png' alt='a picture'>"); is easier than escaping the quotes, which gives you document.write("<img src=\"images/pic.png\" alt=\"a picture\">");
All documents should specify UTF-8 encoding via <meta charset="utf-8"> (not needed for css since uft-8 is assumed)
All documents should be declared as using the HTML5 document type via <!DOCTYPE html>
Use HTML elements for their intended purpose e.g. use <h1> for a level-1 heading; to bold and centre text, use a <p> element with appropriate styles to bold and centre.
Keep structure (html), presentation (styles), and functionality (scripts) separate e.g. an html file should only contain html structure and content, all "look-and-feel" should go in css and all functions, and functional code should go in JavaScript or PHP files.

All block and table elements should start on a new line. Examples:

<ul>
  <li>List Item</li>
  <li>List Item</li>
</ul>

<table>
  <tr>
    <th>Heading</th>
    <th>Heading</th>
  </tr>
</table>

CSS Standards

In addition to the general standards and conventions already mentioned, the following apply to CSS and should be used in all submissions in this course:

All css must be valid.
All rules begin on their own line.
Always add a blank line between rules.
A rule with multiple selectors separated by commas: each selector must go on its own line, e.g.
```
header,
                footer,
                main {
                    ...
                }
```
All rules use end-of-line brace style; never use next-line brace style (the opening brace must go on the same line as the selector (or last selector, if there are multiple) and there must be a space between the selector and the opening brace).

Declarations inside a rule should be alphabetized. For example:

.main-box {
  background: #003;
  border: 1px dashed #000;
  border-radius: 4px
  -moz-border-radius: 4px;
  -webkit-border-radius: 4px;
  color: #fff;
  margin: 5px;
  padding: 2px;
}

Always end each declaration with semi-colon, even the last one in a block.
Each declaration should go on its own line (see alphabetized example above).
All declarations must indent 2 spaces; each declaration must be on its own line.
Declarations always consist of property: value -- there must be a colon immediately after the property name, followed by a space, followed by the value(s)

Always use shorthand properties where possible, e.g. do this:

header {
                      border: .2em solid navy;
                    }

INSTEAD OF THIS:

header {
                        border-color: navy;
                        border-style: solid;
                        border-width: .2em;
                    }

Use double quotes instead of single quotes where needed; url() doesn't need quotes at all.
Use comments to group related rules into sections e.g header/footer rules, table styling rules, etc.
CSS identifiers (e.g. class names, id names, etc) must be in all lower-case; separate words with hypens (-). E.g. score-card, not scoreCard, scorecard, SCORECARD, etc.
Make rules and selectors modular and re-usable: avoid using #id selectors whenever possible.