Swinburne JavaScript Coding Standards

From SwinBrain

Contents

Introduction

If you are writing code to be read or used by others - as you do during assignment work - you should always try to create work that is well organised, formatted and commented in such a way that it communicates effectively. When your work is assessed, you want the reader to appreciate your good work!

Unlike the faculty Swinburne HTML Coding Standards, or the faculty Swinburne Java Coding Standard, we do not as yet have strict commenting or formating standards for JavaScript. This is also in part because people using JavaScript often have a variety of programming backgrounds, and may favour other established language conventions and apply them to JavaScript.

Guidelines

The following are guides you should use in your work.

General Organisation

When using JavaScript with HTML files, use:

  • a single common JavaScript file for common functions and global data (eg. script.js or common.js)
  • specific JavaScript files for a modules of work (eg menu.js or search.js)
  • a specific JavaScript file for functions that are only required once for a single HTML file. (eg. tictactoe.js)

Depending on the project (or assignment), you may be asked to place all your functions and other global variables into a single file, as this can make debugging (and marking) central.

However, for larger real-world projects it makes more sense to divide your code into separate files of "common" functions and data, and separate files for module or page specific code. Remember that JavaScript code can be cached just like HTML, CSS and image files, so try to take advantage of that as much as you can, place common code in common external files, specific code in specific files, and improve the speed of the user experience.

Use .js File Extension

This is not a requirement of web browser or HTML, but is a sensible convention and ensure that your code files will recognised as such by many common text editors (with features like code-syntax-highlighting that uses file name extension detection).

Function Names and Function Order

Use a sensible function name stragtegy and stick to it throughout your work. Some conventions use a CapitalLetterForEachMainWord() or the Under_Score_Separation(). Whatever you select, be consistent!

If you have a large number of functions, sort them by alphabetical order, or - at a minimum - group them into sensible (related) modules and clearly comment each group. Good for you, and good for others.

Avoid Inline JavaScript Code in HTML

Two very strong recommendations:

  • Do NOT place functions or other unnecessary JavaScript in the HTML document.
  • Avoid the use of HTML attributes for event handler code. Use event registering methods instead.

Although it is possible and legal to place your JavaScript code in script elements anywhere within an HTML head or body element, this is counter to the idea of separating web development working into clean layers.

  • HTML for content,
  • CSS for presentation, and
  • JavaScript for added client-side interactivity.

Through the use of event registering, it is possible to bind functions to events of HTML elements without using "onmouseover" attribute values directly in your HTML.

File Header Comments

Include a header comment block that states. Your exact format can vary but using an established standard like JavaDoc is highly recommened.

/**
 * Author: (Your name and student ID)
 * Purpose: Form validation support routines (or whatever you need)
 * Created: ??
 * Last updated: ??
 * Credits: (Any guidance/help/code? Credit it here.)
 */

Function Comments

Before each function, add a method comment block to tell us what it does. Again, the use of a known standard is like JavaDoc is encouraged, but not required.

/**
 * Perform "world domination". Requires a large amount of money
 * as a parameter. Assumes a small world. Returns a lunchbox.
 */
function DominateWorld(money)
{
  // Spend money on lunchbox etc ...
}

Inline Comments

Include single line comments in functions to explain what's happening.

  • Too Few is Bad: If its more than a basic language feature, make a note. Also, assignment work will be read. You need to demonstrate what you know. Uncommented code does not help you convince a maker that you know what you are doing.
  • Too Many is Bad: Assume that your reader does have a similar level of knowledge to yourself. There really is no point commenting what the word "function" means, or an "if" statement or the "return" statement! If you have more comments than code, somethings probably not right! (See "Aren't Comments Bad for Performance").
Tip: Don't go crazy with inline comments. Think about what you would need to read to understand your code, and comment at that level.

Other Considerations

Aren't Comments Bad for Performance?

Yes, but that's not the point for assignment work.

Some argue that in the real world JavaScript should be stripped down to the bear minimum to reduce the download cost for client -- every character counts! However, for assignment work your primary goal is to demonstrate your work and your understanding, not to minimize file size.

It is relatively easy for a production site to "strip" comments out (and other unnecessary white space) from all code (HTML, CSS and JavaScript) at a later stage, but still keep a set of fully commented "development" files.

Unobtrusive JavaScript

Always try to follow the principle of unobtrusive JavaScript. Do not make an interface depend on JavaScript to work, so that if JavaScript is disabled, your work will still function. That said, JavaScript is a great way to enhance a user interface and speed-up interaction.