What are Comments in Programming?

Comments are notes written inside source code to explain the program. They are written for humans, not for the computer.

Comments help programmers understand what the code does, why a certain logic is used, and how different parts of the program work. When a program runs, comments are ignored by the computer, compiler, or interpreter.

Comments are useful in almost every programming language. They are commonly used to explain logic, document important sections, improve readability, and temporarily disable code during testing or debugging.

Easy Real-Life Example

In programming, comments work in the same way. Code tells the computer what to do, while comments help humans understand the code.

Why are Comments Important?

Comments are important because programs are not only written once; they are also read, tested, updated, debugged, and maintained many times. A programmer may return to the same code after days, weeks, or months. Good comments make the code easier to understand.

Simple Example of a Comment

The following example shows a simple comment written before a line of code.

// Display a welcome message.
print("Welcome to Programming")

Here, the comment explains the purpose of the code. The computer ignores the comment and only executes the actual instruction.

Types of Comments

Different programming languages support comments in different ways. However, the most common types of comments are single-line comments, multi-line comments, and documentation comments.

Common Comment Styles Across Languages

Comment symbols may differ depending on the programming language. The table below shows common comment styles.

1. Single-Line Comments

A single-line comment is used to write a short explanation on one line. It is best for brief notes.

Example

// Store the student's age.
age = 18

// Display the student's age.
print(age)

The comments explain what the code is doing, but they do not affect program execution.

Python-Style Example

# Store product price.
price = 100

# Display product price.
print(price)

Some languages, such as Python, use # for single-line comments.

2. Multi-Line Comments

A multi-line comment is used when the explanation is longer than one line. It is useful for describing a block of logic or giving a longer note.

Example

/*
This program calculates the total marks
of three subjects and displays the result.
*/

mathMarks = 80
scienceMarks = 75
englishMarks = 85

totalMarks = mathMarks + scienceMarks + englishMarks
print(totalMarks)

Multi-line comments are useful when a single-line comment is not enough to explain the logic.

3. Documentation Comments

A documentation comment is used to describe important parts of a program such as functions, classes, modules, parameters, and return values.

Documentation comments are common in professional software development because they help create structured documentation.

Generic Documentation Comment Example

/**
 * Calculates the total price of a product.
 *
 * Parameters:
 * price - The price of one product.
 * quantity - The number of products.
 *
 * Returns:
 * The total price.
 */

This type of comment helps other developers understand how a function or module should be used.

Comments vs Code

Comments and code are different. Code is executed by the computer, while comments are ignored.

Using Comments for Debugging

Comments can also be used to temporarily disable a line or block of code while testing. This is called commenting out code.

Example

print("Line 1")

// print("Line 2")

print("Line 3")

Output

Line 1
Line 3

The second print statement is ignored because it has been commented out.

Good Comments vs Poor Comments

Good comments explain why something is done. Poor comments only repeat what the code already says.

Poor Comment Example

// Add number1 and number2.
sum = number1 + number2

This comment is not very useful because the code is already easy to understand.

Better Comment Example

// Apply bonus marks before calculating the final result.
totalMarks = totalMarks + bonusMarks

This comment is more useful because it explains why the value is being updated.

Best Practices for Writing Comments

Comments should be helpful, clear, and professional. Too many unnecessary comments can make code messy.

Professional Comment Formatting

A professional comment should be easy to read and consistent with the coding style of the project.

Good Formatting

// Calculate the final amount.
finalAmount = price * quantity

Poor Formatting

//calculate final amount
finalAmount = price * quantity

Complete Example Using Comments

The following example shows comments in a language-neutral style.

/*
This program calculates the total and average marks
of a student.
*/

// Store student name.
studentName = "Ravi"

// Store marks of three subjects.
mathMarks = 80
scienceMarks = 75
englishMarks = 85

// Calculate total marks.
totalMarks = mathMarks + scienceMarks + englishMarks

// Calculate average marks.
averageMarks = totalMarks / 3

// Display final result.
print("Student Name: " + studentName)
print("Total Marks: " + totalMarks)
print("Average Marks: " + averageMarks)

Expected Output

Student Name: Ravi
Total Marks: 240
Average Marks: 80

Common Beginner Mistakes

Prerequisites Before Learning Comments

To understand comments properly, students should know a few basic programming concepts.

Practice Activity: Add Comments

This activity helps students practice writing useful comments in a program.

Task

price = 100
quantity = 3

totalAmount = price * quantity

print("Total Amount: " + totalAmount)

Sample Answer

// Store product price.
price = 100

// Store product quantity.
quantity = 3

// Calculate total bill amount.
totalAmount = price * quantity

// Display total amount.
print("Total Amount: " + totalAmount)

Mini Quiz

Interview Questions on Comments

Quick Summary

What are Comments in Programming?

Comments are notes written inside source code to explain the program. They are written for humans, not for the computer.

Comments help programmers understand what the code does, why a particular logic is written, and how different parts of the program work. When a program runs, comments are ignored by the compiler or interpreter.

In Java, comments are commonly used to explain code, document classes and methods, and temporarily disable code during testing or debugging.

Easy Real-Life Example

Code tells the computer what to do. Comments tell humans why the code exists or how it works.

Why are Comments Important?

Comments are important because programs are often read many times after they are written. A programmer may return to the same code after days, weeks, or months. Good comments make the code easier to understand.

Simple Example of a Comment

The following Java program contains a comment.

public class Main {
    public static void main(String[] args) {
        // Display a welcome message.
        System.out.println("Welcome to Java");
    }
}

Here, the line starting with // is a comment. It explains what the next line of code does.

Types of Comments in Java

Java mainly supports three types of comments.

Java Comment Syntax Summary

1. Single-Line Comments

A single-line comment is used to write a short explanation on one line. It starts with two forward slashes //.

// This is a single-line comment.

Everything written after // on the same line is treated as a comment.

Example

public class Main {
    public static void main(String[] args) {
        // Store student age.
        int age = 18;

        // Display student age.
        System.out.println(age);
    }
}

Output

18

The comments explain the purpose of the statements, but they do not affect the output.

2. Multi-Line Comments

A multi-line comment is used when the explanation is longer than one line. It starts with /* and ends with */.

/*
This is a multi-line comment.
It can continue for multiple lines.
*/

Example

public class Main {
    public static void main(String[] args) {
        /*
        This program calculates the total marks
        of three subjects and displays the result.
        */

        int math = 80;
        int science = 75;
        int english = 85;

        int total = math + science + english;

        System.out.println("Total Marks: " + total);
    }
}

Output

Total Marks: 240

Multi-line comments are useful when we need to explain a complete section of code.

3. Documentation Comments

A documentation comment is a special type of comment used to create documentation for classes, methods, constructors, and fields.

Documentation comments start with /** and end with */.

/**
 * This is a documentation comment.
 */

Example

/**
 * The Calculator class performs basic arithmetic operations.
 */
public class Calculator {

    /**
     * Adds two numbers and returns the result.
     *
     * @param number1 The first number.
     * @param number2 The second number.
     * @return The sum of number1 and number2.
     */
    public int add(int number1, int number2) {
        return number1 + number2;
    }
}

Documentation comments are useful in professional projects because they can describe how classes and methods should be used.

Common Javadoc Tags

Documentation comments often use special tags to describe parameters, return values, authors, and versions.

Comments vs Code

Comments and code are different. Code is executed by the computer, but comments are ignored.

Using Comments for Debugging

Comments can be used to temporarily disable a line or block of code while testing. This is called commenting out code.

Example

public class Main {
    public static void main(String[] args) {
        System.out.println("Line 1");

        // System.out.println("Line 2");

        System.out.println("Line 3");
    }
}

Output

Line 1
Line 3

The second output statement is ignored because it has been commented out.

Good Comments vs Poor Comments

A good comment explains why something is done. A poor comment simply repeats what the code already says.

Poor Comment Example

// Add number1 and number2.
int sum = number1 + number2;

This comment is not very useful because the code is already easy to understand.

Better Comment Example

// Apply extra marks before final result calculation.
totalMarks = totalMarks + bonusMarks;

This comment is more useful because it explains why the value is being updated.

Best Practices for Writing Comments

Comments should be helpful, clear, and professional. Too many unnecessary comments can make code messy.

Professional Comment Formatting

A professional comment should be easy to read and consistent with coding standards.

Good Formatting

// Calculate the final amount.
int finalAmount = price * quantity;

Poor Formatting

//calculate final amount
int finalAmount = price * quantity;

Complete Java Example Using Comments

The following program uses different types of comments.

/**
 * This program calculates the total and average marks of a student.
 */
public class StudentResult {
    public static void main(String[] args) {
        // Store student name.
        String studentName = "Ravi";

        // Store marks of three subjects.
        int mathMarks = 80;
        int scienceMarks = 75;
        int englishMarks = 85;

        /*
        Calculate total marks and average marks.
        These values will be displayed as final output.
        */
        int totalMarks = mathMarks + scienceMarks + englishMarks;
        int averageMarks = totalMarks / 3;

        // Display final result.
        System.out.println("Student Name: " + studentName);
        System.out.println("Total Marks: " + totalMarks);
        System.out.println("Average Marks: " + averageMarks);
    }
}

Output

Student Name: Ravi
Total Marks: 240
Average Marks: 80

Common Beginner Mistakes

Prerequisites Before Learning Comments

To understand comments properly, students should know some basic programming concepts.

Practice Activity: Add Comments

This activity helps students practice writing useful comments in Java code.

Task

public class ProductBill {
    public static void main(String[] args) {
        int price = 100;
        int quantity = 3;

        int totalAmount = price * quantity;

        System.out.println("Total Amount: " + totalAmount);
    }
}

Sample Answer

public class ProductBill {
    public static void main(String[] args) {
        // Store product price.
        int price = 100;

        // Store product quantity.
        int quantity = 3;

        // Calculate total bill amount.
        int totalAmount = price * quantity;

        // Display total amount.
        System.out.println("Total Amount: " + totalAmount);
    }
}

Mini Quiz

Interview Questions on Comments

Quick Summary