Comments in Programming

Why Use Comments?

Good comments make code understandable and maintainable.

Comments can:

• Explain complex logic
• Describe the purpose of functions, classes, or files
• Mark sections that need improvement
• Make collaboration with others easier
• Debug code by temporarily disabling lines or blocks

Types of Comments

Most programming languages support several types of comments:

1. Single-line Comments

Used for short explanations or notes.

Either as a whole line:

//this line is a comment
print("Hello");

or at the end of a line:

print("Hello"); //this is a comment

2. Multi-line Comments

Used for longer explanations. Syntax varies by language.

/*This is a comment
that spans over
multiple lines*/
print("Hello");

3. Inline Comments

Comments can also appear inside a line of code. In languages that support multi-line comments, you can place a comment in the middle of a statement.

This is sometimes used to quickly change a value or logic for testing.

firstname = /*"John"*/"Jane";
print("Hello " + firstname);

Note: This technique does not work in Python, as Python does not support block comments inside statements.

Comments in Different Languages

Inline Comments

Inline comments are comments that appear on the same line as code, or even inside a line of code. They are useful for explaining a specific part of a statement, or quickly changing code for testing and debugging.

• In-line (mid-line) comments: Placed inside a statement.
• End-of-line inline comments: Placed after a statement to explain its purpose.

let x = 10;
let y = /*5*/ 7;
let z = x + y;
console.log(z); // outputs 17

int x = 10;
int y = /*5*/ 7;
int z = x + y
System.out.println(y); // Output: 17

int x = 10;
int y = /*5*/ 7;
int z = x + y;
printf("%d\n", y); // Output: 17

int x = 10;
int y = /*5*/ 7;
in z = x + y;
std::cout << y << std::endl; // Output: 17

<p>Hello <!-- John --> Jane!</p> <!-- Outputs 'Hello Jane' -->

SELECT * FROM Customers
WHERE city = /*'London'*/ 'Berlin'; // Returns all customers from Berlin

Using Comments for Debugging

Comments are not just for documentation—they can also be a powerful debugging tool. When troubleshooting code, you can temporarily "comment out" lines or blocks to isolate problems or prevent certain code from running.

• Comment out code: Disable parts of your code without deleting them, making it easy to restore later.
• Test changes safely: Try new logic while keeping the original code as comments for reference.
• Isolate bugs: By commenting out sections, you can narrow down where errors are happening.

# Debugging by commenting out a line
x = 10
y = 0
# y = 5
result = x + y
print(result)

// Debugging by commenting out a line
let x = 10;
let y = 0;
// y = 5;
let result = x + y;
console.log(result);

// Debugging by commenting out a line
#include 
using namespace std;
int main() {
  int x = 10;
  int y = 0;
  // y = 5;
  int result = x + y;
  cout << result << endl;
  return 0;
}

// Debugging by commenting out a line
public class Main {
  public static void main(String[] args) {
    int x = 10;
    int y = 0;
    // y = 5;
    int result = x + y;
    System.out.println(result);
  }
}

<!-- Debugging by commenting out a line -->
<!-- <p>This paragraph is temporarily hidden for debugging</p> -->
<p>Hello, world!</p>

-- Debugging by commenting out a line
-- SELECT * FROM Cutomers;
SELECT * FROM Products;

# Debugging by commenting out a line
# rm important_file.txt
echo "Safe for now!"

Tip: Remember to remove or update debugging comments before finalizing your code to keep it clean and maintainable.

Best Practices for Comments

• Write clear and concise comments
• Keep comments up-to-date with your code
• Don't state the obvious (avoid "increment x by 1" for x += 1)
• Use comments to explain why, not just what
• Remove outdated or misleading comments

Summary

Comments are a vital tool for making your code readable, maintainable, and collaborative. Use them wisely!