Home Commenting Guidelines
File Headers
Place a descriptive comment heading on the top of every file describing that file's purpose. Assume that the reader of your comments is an intelligent programmer but not someone that has seen this assignment (or spec) before. Your comment header should include at least your name, course/section, date, and a brief description of the assignment. If the assignment asks you to submit multiple files, each file's comment header should describe that file/class and its main purpose in the program.
Here are two bad examples of an HTML file comment - these also serve to represent poor comments in CSS/JavaScript/PHP file comments, which should differ only in the summary description.
<!-- Bad HTML File Comment 1 Missing student name, date, course, and descriptive summary of the file. --> <!-- Instructor's Name: Whitaker This is a file for my assignment. -->
<!-- Bad HTML File Comment 2 Uses uw netid instead of student's full name, date is not specific, missing course/section information, and missing a descriptive summary of the file. --> <!-- Name: uwnetid12 Date: Monday -->
Here is a good example of an HTML file comment.
<!-- Name: Melissa Galloway Date: 04.15.17 Section: CSE 154 AX This is the index.html page for my portfolio of web development work. It includes links to side projects I have done during CSE 154, including an AboutMe page, a blog template, and a crytogram generator. -->
Function Headers
Function Commenting Format
Place a comment heading on each function you declare (in JavaScript and PHP). The heading should clearly describe the function's behavior, including specification of any parameters, return types, and special cases (e.g., returning a value of -1).
For JavaScript code, we ask that you use JSDoc commenting syntax. This syntax provides a clear template for declaring parameters, return types, and special cases. If you have used JavaDoc before, this is a similar commenting style, only for JavaScript.
In this class, we expect you to use the @param and
@returns
annotation tags in JSDoc when appropriate for the function. The @param
annotation specifies the name and type of each parameter, as well as what the purpose of that
parameter is in the function. The @returns annotation specifies the type
and expected value of what is returned given the parameters and any other conditions
of the function. You do not need to use any other JSDoc annotations in CSE 154.
Here is an example of a function comment skeleton as reference:
// Single-line JSDoc comment:
/** Your comment here */
// Multi-line JSDoc comment:
/**
* brief description of the function
* @param {datatype} parameterName1 - parameter description
* @param {datatype} parameterName2 - parameter description
* @returns {datatype} Description of the returns value
*/
function functionName() {
}
Here are examples of function comments written in JSDoc:
// prints stuff on the computer
function printCurrentTime() {
...
}
// Good comment with JSDoc format
/**
* Prints the current time on the console, in the format HH:MM DD/MM/YYYY.
* For example, 22:23 (or 10:23 PM in US Time) on April 15th, 2017 would
* be printed as 22:23 15/04/2017.
*/
function printCurrentTime() {
...
}
/**
* Changes the background of an HTML DOM element to a random color.
* @param {string} elementID - id of the HTML DOM element whose color is
* to be changed
*/
function changeBackgroundColor(elementId) {
let colorOptions = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
"A", "B", "C", "D", "E", "F"];
let randomColor = "#";
for (let i = 0; i < 6; i++) {
randomColor += colorOptions[Math.floor(Math.random() * 16)];
}
document.getElementById(elementId).style.backgroundColor = randomColor;
}
/**
* Returns the sum of value1 and value2
* @param {number} value1 - first number for addition
* @param {number} value1 - second number for addition
* @returns {number} sum of value1 and value2
*/
function sum(value1, value2) {
return value1 + value2;
}
/**
* Returns the element that has the ID attribute with the specified value.
* @param {string} id - element ID
* @returns {object} DOM object associated with id.
*/
function $(id) {
return document.getElementById(id);
}
PHP Comment Types
In PHP, you may use # or
// for single-line comments as long as you are consistent in your
usage. PHP multi-line comments are the same as JS (/* ... */).
PHP function comments should meet the same standards as those in JS, but
you do not need to use the JSDoc tags (@param or
@returns). You should still comment
on all function parameters and returns though. If parameters are clearly explained
in the comment, you can omit redundant descriptions as in the example below:
/**
* Returns the average value of $x, $y, and $z as a float:
* @param {number} $x
* @param {number} $y
* @param {number} $z
* @returns {number} - average of $x, $y, $z
*/
function get_average($x, $y, $z) {
# Inline comments are good to specify important parts of longer/more complex functions
...
}
Anonymous Functions
Every function should be commented - this includes anonymous functions. With the
exception of the window.onload function, anonymous
functions tend to be less meaningful than other named functions (otherwise they
should be factored out as meaningful functions instead of being anonymous). You do
not need to use @param and @returns in anonymous functions
since they tend to be attached as event handlers to elements, but you should still
comment on the role of the anonymous function.
The window.onload function is especially important to comment in your
JS programs in this class. This function has a key role in the program: it sets up
the initial behavior on the page, adding important event listeners, dynamically
uploading or fetching data onto the page, etc. When writing a comment for
window.onload, you should specify what behavior is "set up" when the
page is initially loaded.
// sets up the page, attaches button handler
window.onload = function() {
fetchDuckPhotos();
document.getElementById("more-ducks-btn").onclick = fetchMoreDucks;
};
/**
* Initiates the page, populating the section of duck product photos with ducks from the
* Ducky API and allows a user to click the "More Ducks" button to fetch even more duck photos.
*/
window.onload = function() {
fetchDuckPhotos();
document.getElementById("more-ducks-btn").onclick = fetchMoreDucks;
};
Wording
Your comment headers should be written in complete sentences and should be written in your own words, not copied from other sources (such as copied verbatim from the homework spec document).
Parameters and Returns
If your function accepts parameters, briefly describe their purpose and meaning. If your function returns a value, briefly describe what it returns.
// does math on numbers
function multiply(x, y) {
return x * y;
}
// A good comment with JSDoc
/**
* Returns the product of the two given numbers (defined as x * y)
*
* @param {number} x - first (number) factor value of returned product
* @param {number} y - second (number) factor value to returned product
* @returns {number} product of x * y
*/
function multiply(x, y) {
return x * y;
}
Implementation Details
Comment headers at the top of a function or class should describe the function's
behavior, but not great detail about how it is implemented (just as you may be
familiar with from CSE 14X style guidelines). Do not mention language-specific
details like the fact that the function uses an if/else statement,
that the function declares an array, that the functions loops over a collection
and counts various elements, etc.
Inline Comments
Inside the interiors of your various functions, if you have sections of code that are lengthy or complex or non-trivial, place a small amount of inline comments near those lines of complex code, describing what they are doing. You should also always comment module-global variables or constants with an inline comment to describe their role in your program (see example below). Since it's important to reduce the number of module-global variables, it's important to justify the purpose of each in the context of your overall program.
In this class, this helps your TA understand your logic behind complex code. In general, this helps other developers working on the same code with you (as well as your future self) to understand the logic behind your code.
(function() {
const DEFAULT_QUIZ_LENGTH = 30000; /* Quizzes are 30 seconds long by default */
let quizTimer; /* The timer variable for keeping track of time left on the quiz */
/* Rest of your program */
})();