Cs.franklin.edu



ITEC 136 Coding Conventions

Lab assignments will be graded in at least the following areas:

• Correct results – the program should work, and be seen to work. This involves not only producing correct output, but also reacting well to user error, incorrect input, etc. The code should be robust. Test it thoroughly.

• Coding standards – It is not uncommon for industry to impose a way of writing software that is uniform across all programmers. For the purpose of this class, we have the following:

o The use of variable names that is descriptive of the use of the variable. Variable names should follow camelCaseConventions,. For instance, use the variable name hoursWorked to keep track of the number of hours a person has worked, instead of using x.

o Limit the number of global variables used.

o Each function should perform one task, and no function should reasonably exceed 50 lines (this is a guideline, not a rule; I won’t be counting lines). Function names should follow camelCaseConventions, and be descriptive of their purpose.

o Symbolic constants should be named descriptively, and be in all upper case letters (i.e. var PI = 3.1415926535)

o No line should exceed 80 characters in length.

o Indent the body of blocks (while loops, if statements, for loops, etc.) and tags (in HTML) consistently using 4 spaces (not tabs). You may want to adjust your editor to substitute spaces for tabs.

o Code one statement per line, and leave blank lines to separate out logically connected chunks of code.

o Follow structured programming techniques. These include writing modular code having only one entry point, and one exit point.

o Write standard, portable code. Your programs will be tested in FireFox 3.5 or greater.

• Documentation – Good programs require more explanation than is available in the code listing itself. It is required that you place comments throughout your code that explain the workings of your algorithms, the use of variables, any special or tricky points of code, and any modifications of global variables. When in doubt, write comments. If all your code were stripped out, a reader should still be able to follow your thought process as you were programming.

In addition, you will need to follow a special commenting format for files and functions. These conventions were adapted from the JSDoc project (a tool that will automatically generate API documentation from Javascript files ). For the purpose of this class, we have the following:

o A comment box at the beginning of the file that has the following format (the first is for Javascript and the second is for HTML):

/**

* A description of what the program does goes here. This

* should be a general restatement of the assignment.

*

* @author Your Name Here

* @version 1/31/2010 (i.e. the due date)

*/

o Each function should be documented with a comment block similar to the following:

/**

* A description of what the function does goes here.

* Remember that documentation tells what the function

* _should_ do, not what it actually does. So, for a

* makeBold function you would write: This function will

* take the input text and return it surrounded by ""

* and "" effectively making it bold.

*

* @param {String} a string to convert to bold

* @return {String} a bolded string suitable for rendering

*/

function makeBold(text) {

// code goes here

}

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download