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 */
})();

Commented-Out Code

It is considered poor style to turn in a program with chunks of code "commented out". It's fine to comment out code as you are working on the program, but you should always make sure to remove any such code before submitting your assignment.