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).
If you'd like, you may 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.
// 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() {
...
}
// Good comment without JSDoc format (there isn't much difference here
// since there are no parameters/return types to comment.
/*
* 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() {
...
}
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 x - first (number) factor value of returned product
* @param y - second (number) factor value to returned product
* @requires x and y are both Number types
* @returns product of x * y
*/
function multiply(x, y) {
return x * y;
}
// A good comment without JSDoc
// Returns the product of the two given numbers (defined as 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.
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.