The AP Computer Science A 5-hour live stream review is here!Β πŸ’»

Join us on May 5, 2021 for the 🌢️ AP Computer Science A Cram Finale for a last minute review to get all your questions answered!


All Subjects

Β >Β 


AP Comp Sci A

Β >Β 


Unit 5

5.3 Documentation With Comments

3 min readβ€’november 16, 2020

Peter Cao

Now, we will learn one of the most useful features of Java: commenting and documentation. This allows us to write clear code and understand it. This will also allow readers to understand our code. With comments, we are explaining our code in easy to use words. These comments will not be compiled by the Java compiler.

Types of Comments and Their Uses

There are three types of comments, two which have the same purpose and one that has a more specific use.

Single-Line and Multi-Line Comments

Single-line comments are comments that are on one line while multi-line comments (also called block comments) are comments that span multiple lines. These types of comments are for explaining sections of code that may not be self-explanatory, especially before loops or if-else statements. However, we do not comment on code that is obvious. Here is an example of each:
// This is a single line comment. You start one with the // /* This is a multi-line comment. There is a lot to be said in this comment * that cannot be fit in one line, you start one with /* and end it with */

Javadoc Comments

Javadoc is the other type of comment that we will be looking at. Javadoc comments create documentation such as the class documentations we looked at back in Unit 2! These are very helpful, as from these, we can figure out what methods and classes do and how to use them. These are used only before methods and classes. Here is an example:
/** This a description of what the class, method, or constructor does, you start this * with /** (note that this has 2 asterisks instead of one) * and end like a multi-line comment. * * Here, you also put preconditions as well, which are constraints * that your input must follow as well as postconditions, which * are constraints that the output must follow. These can also be put into * regular comments as well. Preconditions have to be enforced by the user * and the programmer has no obligation to check for faulty output, however if * the programmer does, this is done with the use of try-catch and throw statements * which are beyond the scope of this unit's goals. */

Commenting our Two Classes

Using what we have learned, we will comment and document the two classes we have been working on!
/** Represents an assignment that a student will complete */ public class Assignment { private boolean correctAnswer; // represents the answer to an assignment, either T/F /** Makes a new assignment with one True/False question and sets the correct answer */ public Assignment(boolean answer) { correctAnswer = answer; } } /** Represents a high school student */ public class Student { private int gradeLevel; // a grade between 9-12 private String name; // the students name in the form "FirstName LastName" private int age; // the student's age, must be positive private Assignment assignment; // the current assignment the student is working on /** Makes a new student with grade gradeLev, name fullName, and age ageNum */ public Student(int gradeLev, String fullName, int ageNum) { gradeLevel = gradeLev; name = fullName; age = ageNum; averageGrade = 0; // There is no grade since no assignments have been submitted assignment = null; // There is no active assignment at the moment } }

Was this guide helpful?

πŸ’ͺ🏽 Are you ready for the Comp Sci exam?
Take this quiz for a progress check on what you’ve learned this year and get a personalized study plan to grab that 5!
FREE AP comp sci a Survival Pack + Cram Chart PDF
Sign up now for instant access to 2 amazing downloads to help you get a 5
Browse Study Guides By Unit
Exam Reviews
Unit 10: Recursion
Unit 1: Primitive Types
Unit 2: Using Objects
Unit 3: Boolean Expressions and if Statements
Unit 4: Iteration
Unit 6: Array
Unit 7: ArrayList
Unit 8: 2D Array
Unit 9: Inheritance
Join us on Discord
Thousands of students are studying with us for the AP Computer Science A exam.
join now