CSc 337: Code Style Requirements

Note: Some of these requirements may apply to concepts not yet covered, depending on what point in the semester you are reading this at.

Universal Rules

You are required to have a header commend at the beginning of every file that you submit for assignments in this class. The header file should at minimum include your name, and a several-sentence description of the purpose of the file. This includes HTML CSS, and JS files. As you might expect, the exact way in which one writes commends for each of these languages differs, so use the appropriate commenting format.

HTML Rules

The primary rule for HTML style in this course is that All HTML that you submit must be fully valid. You should use The W3 Validator to ensure this before you submit an assignment. I also recommend that you stick to a consistent naming pattern for HTML element classes and IDs.

CSS Rules

For this class, you should not inter-mix CSS and HTML. This will sometimes be done in the class videos when working through a quick example, but for all larger scale websites and applications, it is best-practice to keep your HTML separate from CSS. Put the CSS into .css files and then import it from HTML.

Javascript Rules

Commenting

You should place comments above or next to any block of code that completes a non-trivial tasks. For example, you are not required to place a comment immediately above this code:

var name = document.getElementById("nameField").value;
if (name.length > 20) {
    alert('That name is too long!');
}

Because, it is fairly obvious just by looking at it what it is accomplishing (assuming the reader knows javascript, of course). However, on a block of code like this:

var bigData = fetchStatsFromServer(statID);
for (var i = 0; i < bigData.length; i++) {
    for (var j = 0; j < bigData[i].length; j++) {
        if (i > 2 && bigData[i][j].length > 0) {
            processDataElement(bigData[i][j], statID);
        }
    }
}

You should place one or more comments above it, describing what it is accomplishing, because it is not clear just by reading it what the purpose of the code is.

You should include a function comment for each function that you write, other than main. The comment should describe the task that the function performs. It should also describe each of the parameters.

Variable Naming

You should name all of your variables according the typical js style guidelines. You should use camelCase for all variable and function names, and CamelCase for class names.

General/Misc Code Structure

You should do your best to submit code that is well-structured and easy-to-read. Some guidance for this:

• Chunk your lines of code into groups. If there are several lines of code in-a-row that all help achieve the same small task, you should group them together with no spaces in-between. Then, you can put an empty space before the next block of code.
• You may use either 2 or 4 spaces for indentation.
• You should keep all of your lines of code less than 100 characters wide. If you have a line of code that is wider, consider re-writing it to be in two separate statements.

Function Structure

When using functions in your program, have each function accomplish a specific task. Don’t try to cram too much functionality into one function. If you find yourself writing the majority of your code for a PA in a single function, refactor. If you find yourself writing one function that is more than 30 lines of code, refactor.