WC.3: DOCUMENTATION WITH COMMENTS

OBJECTIVE

I can:

describe the functionality and use of program code through comments

Adding comments to your code helps to make it more readable and maintainable.

Software development is usually a team effort where many programmers will use your code and maintain it for years.

Commenting is essential in this kind of environment and is a good habit to develop.

Comments will also help you to remember what you were doing when you look back at your code a month or a year from now.

There are three types of comments in Java:

// Single line comment
/* Multi-line comment */
/** Documentation comment */

We have seen single and multi-line comments before in previous lessons, but we haven't talked about the documentation comment yet.

You may have noticed that documentation comments are on the FRQ practice questions!

Java has a cool tool called javadoc that comes with the Java JDK that will pull out all of these comments to make documentation of a class as a web page.

This tool generates the official Java documentation too, for example for the String class.

Although you do not have to use this on the exam, it's a good idea to use the documentation comments for classes, methods, and instance variables.

The compiler will skip over comments, and they don't affect how your program runs.

Comments are for you and other programmers working with you.

Also, I find that comments are one of my most used tools for debugging!

If you have a line or block of code that is giving you errors, you can use comments like a "light switch" to turn them off/on to narrow down what the issue might be.

Here are some examples of good commenting:

Notice that there are some special tags that are used with Java documentation comments.

Here are some of the common tags:

@author is the author of the program

@since is the date the program was released (creation date)

@version is the current version of the program

@param is a description of the parameter of a method

@return is the return value for a method

PRECONDITIONS AND POSTCONDITIONS

As you write methods in a class, it is a good idea to keep in mind the preconditions and the postconditions for the method and write them in the comments.

A precondition is a condition that must be true for your methods to work, for example the assumption that the parameters have values and are not null.

The methods could check for these preconditions, but they do not have to.

The precondition is what the method expects in order to do its job properly.

A postcondition is a condition that is true after running the method.

In other words, it is what the method promises to do.

Postconditions describe the outcome of running the method, for example what is being returned or the change to the instance variables.

These assumptions are very useful to other programmers who what to use your class and get the correct results.

Here are examples of preconditions, postconditions, and @param in the Address Book program:

SUMMARY

Three types of comments in Java inclued /* */, which generates a block of comments, //, which generates a comment on one line, and /** */, which are Javadoc comments and are used to create API documentation.
A precondition is a condition that must be true just prior to the execution of a section of program code in order for the method to behave as expected. There is no expectation that the method will check to ensure preconditions are satisfied.
A postcondition is a condition that must always be true after the execution of a section of program code. Postconditions describe the outcome of the execution in terms of what is being returned or the state of an object.
Programmers write method code to satisfy the postconditions when preconditions are met.

EVIDENCE

1) Complete the following Google Form. This form must be 100% correct and includes released AP practice questions. To stop working and return later, hit submit! You can "edit your response" and continue where you left off.

WC.3 Evidence

Report abuse

WC.3: DOCUMENTATION WITH COMMENTS

OBJECTIVE

Adding comments to your code helps to make it more readable and maintainable.

Software development is usually a team effort where many programmers will use your code and maintain it for years.

Commenting is essential in this kind of environment and is a good habit to develop.

Comments will also help you to remember what you were doing when you look back at your code a month or a year from now.

There are three types of comments in Java:

// Single line comment

/* Multi-line comment */

/** Documentation comment */

We have seen single and multi-line comments before in previous lessons, but we haven't talked about the documentation comment yet.

You may have noticed that documentation comments are on the FRQ practice questions!

Java has a cool tool called javadoc that comes with the Java JDK that will pull out all of these comments to make documentation of a class as a web page.

This tool generates the official Java documentation too, for example for the String class.

Although you do not have to use this on the exam, it's a good idea to use the documentation comments for classes, methods, and instance variables.

The compiler will skip over comments, and they don't affect how your program runs.

Comments are for you and other programmers working with you.

Also, I find that comments are one of my most used tools for debugging!

If you have a line or block of code that is giving you errors, you can use comments like a "light switch" to turn them off/on to narrow down what the issue might be.

Here are some examples of good commenting:

Notice that there are some special tags that are used with Java documentation comments.

Here are some of the common tags:

@author is the author of the program

@since is the date the program was released (creation date)

@version is the current version of the program

@param is a description of the parameter of a method

@return is the return value for a method

PRECONDITIONS AND POSTCONDITIONS

As you write methods in a class, it is a good idea to keep in mind the preconditions and the postconditions for the method and write them in the comments.

A precondition is a condition that must be true for your methods to work, for example the assumption that the parameters have values and are not null.

The methods could check for these preconditions, but they do not have to.

The precondition is what the method expects in order to do its job properly.

A postcondition is a condition that is true after running the method.

In other words, it is what the method promises to do.

Postconditions describe the outcome of running the method, for example what is being returned or the change to the instance variables.

These assumptions are very useful to other programmers who what to use your class and get the correct results.

Here are examples of preconditions, postconditions, and @param in the Address Book program:

SUMMARY

Three types of comments in Java inclued /* */, which generates a block of comments, //, which generates a comment on one line, and /** */, which are Javadoc comments and are used to create API documentation.

A precondition is a condition that must be true just prior to the execution of a section of program code in order for the method to behave as expected. There is no expectation that the method will check to ensure preconditions are satisfied.

A postcondition is a condition that must always be true after the execution of a section of program code. Postconditions describe the outcome of the execution in terms of what is being returned or the state of an object.

Programmers write method code to satisfy the postconditions when preconditions are met.

EVIDENCE

1) Complete the following Google Form. This form must be 100% correct and includes released AP practice questions. To stop working and return later, hit submit! You can "edit your response" and continue where you left off.

WC.3 Evidence