Home Basic expectations for commenting

On commenting

Comments are specially marked lines of text in your code that can be used to describe what's happening in your program. Java ignores comments when it runs your program – rather, comments exist for the benefit of the human reader.

In particular, comments make it easier for humans to understand how to use and modify your code. This is particularly important when working on more complex projects. Larger projects can be hundreds of thousands to millions of lines long, and comments are a useful tool for helping guide somebody new to the codebase.

Class header comments

You must always include class header comments for every class you write. Your class header comment must include metadata (your name, date, assignment, TA, etc), and a description of the class as a whole. Assume that whoever is reading the description is unfamiliar with the assignment.

A class header comment serves one main purpose: to summarize what your program does, and what the purpose of the program is to the reader. It helps a reader who is unfamiliar with your code understand just what your class is doing, on a high level, and gives them enough context to understand what is happening when they go on the read the rest of your code.

When writing a class header comment, you should assume that whoever is reading it is a competent coder, but is unfamiliar with the assignment/has not taken the intro courses at UW. This simulates how you should be writing your comments in the industry.

You should also include some metadata in your class header comment to help your TA keep track of the different submissions while they're grading.

More specifically, you should always include exactly the following things:

Your first and last name
The assignment name and number
The date that you turned the assignment in
Your section id
Your TA's name
A summary of the entire program (at minimum, 2-3 lines long)

Here's an example of what a good class header comment might look like:

// Arthur Dent
// Assignment #10: TeaRobot
// Wednesday, March 14, 2015
// CSE 143, Section AB
// TA: Zaphod Beeblebrox
// 
// This program will control a robot that given a set of constraints
// and taste preferences, will create and serve the user the perfect
// cup of tea.

This is a good class header comment because it contains all of the required metadata, and includes a good summary that strikes a good balance between describing what the program does without being too wordy.

In contrast, here's what a bad class header looks like. It includes barely any metadata, and does not contain a good summary of the program:

// Arthur -- TeaRobot

Here is another example of a bad class header comment. While it does contain the metadata we're looking for, its class header description is too specific and detailed. Your description should be a broad summary of your program, and not a running description of what each and every method is doing.

// Arthur Dent
// Assignment #10: TeaRobot
// Wednesday, March 14, 2015
// CSE 143, Section AB
// TA: Zaphod Beeblebrox
// 
// This program allows you to control the a tea-making robot using the 'makeTea' method,
// which accepts a set of properties for the perfect tea, lets you serve a user using the 
// 'serveTea' method, which accepts a String specifying the name of the person to serve
// tea to, and a 'cleanTable' method which will clean the specified table, wash all the 
// dishes, and such.

Do not plagiarize

Your comments should be written in your own words. You should not directly copy-and-paste any text from the spec.

We want to see if you understand how to write good comments, not how good you are at copying-and-pasting. It's ok to be inspired by the spec, borrow certain phrases from it, and use it to remind you on things to comment on, but you should never copy it wholesale.