Tutorials Home   >   Programming Basics   >   Comments in Programming

Comments in Programming

1. What are Comments?

In programming, comments are lines in the code that are ignored by the compiler or interpreter. They are used to explain what the code does, making it easier for humans to read and understand. Comments do not affect the execution of the program.

Think of comments as notes in your notebook—they help anyone reading the code (including yourself) understand the logic, purpose, or special instructions. Well-written comments make your code maintainable, readable, and collaborative.

2. Why Are Comments Important?

  1. Explain Code Logic – Helps understand complex parts of the program.
    Example: If a loop is performing a specific calculation, a comment can explain why it’s necessary.

  2. Debugging – Programmers can temporarily disable code by commenting it out without deleting it.

  3. Collaboration – When multiple developers work on the same project, comments help everyone understand the code.

  4. Documentation – Comments can serve as documentation to describe how functions, classes, or modules work.

Without comments, code can become difficult to read, even for the person who wrote it.

3. Types of Comments

a) Single-line Comments

Single-line comments are used to comment on one line of code. They usually start with a special symbol depending on the programming language:

  • Python: #

  • C, C++, Java, JavaScript: //

Example in Python:

# This program calculates the area of a rectangle
length = 5
width = 3
area = length * width # area = length multiplied by width
print(area)

Example in Java:

// This program calculates the area of a rectangle
int length = 5;
int width = 3;
int area = length * width; // area = length * width
System.out.println(area);

b) Multi-line Comments

Multi-line comments are used when explanations span several lines.

  • Python: Use triple quotes """ ... """ or ''' ... '''

  • C, C++, Java, JavaScript: Use /* ... */

Example in Python:

"""
This program calculates the area of a rectangle.
We take input from the user for length and width,
and then multiply them to get the area.
"""
length = 5
width = 3
area = length * width
print(area)

Example in Java:

/*
This program calculates the area of a rectangle.
We take input from the user for length and width,
and then multiply them to get the area.
*/
int length = 5;
int width = 3;
int area = length * width;
System.out.println(area);

c) Documentation Comments

Some programming languages, like Java, support special comments for generating automatic documentation. These comments describe classes, methods, or functions in a structured way.

Example in Java:

/**
* This class represents a rectangle.
* It can calculate area and perimeter.
*/
public class Rectangle {
int length;
int width;/**
* Constructor to initialize length and width
*/
public Rectangle(int length, int width) {
this.length = length;
this.width = width;
}

/**
* Method to calculate area
*/
public int getArea() {
return length * width;
}
}

These comments can be processed by tools like Javadoc to create readable HTML documentation.

4. Best Practices for Writing Comments

Writing comments is an art. Poor comments can confuse more than they help. Here are some best practices:

  1. Be Clear and Concise – Avoid writing long paragraphs.
    ❌ Bad: # Here we are doing some calculations for rectangle area using multiplication of two variables which are representing length and width
    ✅ Good: # Calculate area of rectangle

  2. Explain Why, Not What – Code usually shows what is happening. Comments should explain why it’s happening.

  3. Keep Comments Updated – Outdated comments are worse than no comments.

  4. Use Consistent Style – If your team uses # in Python, stick to it.

  5. Avoid Obvious Comments – Don’t write comments for self-explanatory code.

i = i + 1 # Increment i by 1 ❌ unnecessary

5. Commenting Out Code

Programmers often comment out code temporarily while testing or debugging. This is safer than deleting it because you can restore it later.

Example in Python:

# old method
# result = x + y# new method
result = x * y

Example in Java:

// old method
// int result = x + y;// new method
int result = x * y;

6. Advantages of Using Comments

Advantage Explanation
Improves Readability Makes code easier to read and understand.
Simplifies Maintenance Helps programmers quickly understand the logic for fixing bugs.
Facilitates Collaboration Teams can work together more effectively.
Aids Debugging Allows developers to disable parts of code temporarily.
Supports Documentation Especially with documentation comments.

7. Summary

Comments are an essential part of programming. They make code understandable, help with debugging, and support collaboration. There are single-line, multi-line, and documentation comments, each useful in different scenarios. Writing good comments is as important as writing good code—they should be clear, concise, and meaningful. Remember, code is read more often than it is written, so comments are your way of communicating with the future readers (including yourself!).