Introduction to Java Programming.
Chapter 1:
Introduction
1.7 Making
Sense of Your Code: Java Comments
Comments are non-executable statements that
programmers include in their code to explain what the code does, how it works,
and why certain decisions were made. They are completely ignored by the Java
compiler and the JVM, serving solely as documentation for human readers
(including your future self!). Good commenting practices are crucial for code
readability, maintainability, and collaboration in software development.
1.7.1
Single-line Comments (//)
Purpose: Single-line comments are used for short,
concise explanations that fit on a single line. They are ideal for commenting
on a specific line of code or providing a brief note about a variable or
method.
Syntax: They begin with two forward slashes (//).
Everything from the // to the end of the line is considered a comment.
Example:
public class SimpleCommentExample {
public static void
main(String[] args) {
int
score = 100; // Initialize score to 100
System.out.println("Current
score: " + score); // Display the current score
// This is
another single-line comment on its own line
}
}
1.7.2
Multi-line Comments (/* … */)
Purpose: Multi-line comments, also known as block
comments, are used for longer explanations that span across several lines. They
are suitable for providing detailed descriptions of code blocks, algorithms, or
complex logic.
Syntax: They begin with /* and end with */.
Everything between these two delimiters is treated as a comment, regardless of
how many lines it occupies.
Example:
public class MultiLineCommentExample {
public static void
main(String[] args) {
/*
* This is a multi-line comment.
* It can span across multiple lines to
provide more detailed information.
* This particular block of code
calculates the area of a rectangle.
*/
int
length = 20;
int
width = 10;
int
area = length * width; // Calculate area
System.out.println("The area is: " + area);
}
}
1.7.3
Documentation Comments (/** … */)
Purpose: Documentation comments, often called Javadoc comments, are special multi-line comments used to
generate API documentation in HTML format. They are primarily used to describe
classes, interfaces, methods, and fields. The javadoc
tool (part of the JDK) parses these comments and converts them into a
standardized, browsable documentation format. This is
incredibly valuable for large projects and libraries, allowing other developers
to understand how to use your code without needing to read the source code
directly.
Syntax: They begin with /** and end with */. Each
line within the comment typically starts with an asterisk (*). Javadoc comments also support special "tags"
(e.g., @param, @return, @author) to provide
structured information about parameters, return values, and authors.
Example:
/**
* The Calculator class provides basic
arithmetic operations.
* This class demonstrates the use of Javadoc comments for
* generating API documentation.
*
* @author Piyu Patil
* @version 1.0
*/
public class
Calculator {
/**
* Adds two integer numbers and returns
their sum.
*
* @param a The first integer number.
* @param b The second integer number.
* @return The sum
of ‘a’ and ‘b’.
*/
public int add(int a, int b) {
return a + b;
}
/**
* Main method to test the Calculator
class.
*
* @param
args Command line arguments (not used in this
example).
*/
public static void
main(String[] args) {
Calculator calc
= new Calculator();
int
result = calc.add(5, 3); // Example usage
System.out.println("Sum: " + result); // Should print 8
}
}
To generate
the documentation, you would typically run:
javadoc Calculator.java
This would
create an HTML file (and other supporting files) in a doc subdirectory, which
can be viewed in a web browser.
1.7.4 Best
Practices for Using Comments
While comments are useful, they should be used
judiciously. Over-commenting can clutter code, and outdated
comments can be misleading.
When to Use
Comments Effectively:
Explain "Why": Use comments to explain the reason
behind a piece of code, especially if the logic is not immediately obvious.
"Why did I choose this approach?" is often more valuable than
"What does this line do?".
Clarify Complex Logic: For complicated algorithms or intricate code
blocks, a well-placed comment can simplify understanding.
Document Public APIs: Use Javadoc
comments extensively for classes, methods, and fields that are part of a public
interface, so others (and your future self) can easily understand how to use
them without reading the implementation.
Flag TODOs and Fixmes: Use special comments (e.g., // TODO:
Implement error handling here, // FIXME: This logic is incorrect for edge
cases) to mark areas that need further work or correction.
Provide High-Level Summaries: A block comment at the beginning of a method
or class can summarize its overall purpose and responsibilities.
When NOT to Use Comments:
Commenting Obvious Code: Avoid comments that simply restate what the
code already clearly expresses. For example: int x =
10; // Initialize x to 10 is redundant.
Outdated Comments: An incorrect or outdated comment is
worse than no comment at all, as it can actively mislead.
Replacing Bad Code: If code is confusing, comment it after
you’ve tried to simplify it. Comments should explain good code, not excuse bad
code.
Emphasize Writing Self-Documenting Code:
The best code is often "self-documenting."
This means writing code that is clear and easy to understand without needing
many comments. This is achieved through:
Meaningful Variable and Method Names: Use descriptive names (e.g., calculateTotalPrice instead of ctp,
customerAge instead of ca).
Clear Code Structure: Organize your code logically with proper
indentation, spacing, and breaking down large methods into smaller, focused
ones.
Consistent Formatting: Adhere to consistent coding style guidelines.
Keep Comments Updated:
Whenever you modify a piece of code, make sure to
review and update any associated comments. Outdated
comments can be a significant source of confusion and bugs.
By following these practices, your students
will learn to use comments as a valuable tool to enhance their code quality and
promote better software development habits.
