Lesson 4: Java Comments - Complete Guide

1. Comments ဆိုတာ ဘာလဲ?

Comments are text notes in your code that are ignored by the compiler. They are used to explain what the code does, making it easier for you and others to understand the program.

အခြေခံ အဓိပ္ပာယ်

Comments ဆိုတာ code ထဲမှာ ရေးထားတဲ့ မှတ်ချက်တွေ သို့မဟုတ် ရှင်းလင်းချက်တွေ ဖြစ်ပါတယ်။ Compiler က comments တွေကို လုံးဝ လျစ်လျူရှုပါတယ် - compile လုပ်တဲ့ အခါ skip လုပ်သွားပါတယ်။

ဘာကြောင့် လိုအပ်လဲ?

Code ကို နားလည်ရ လွယ်စေတယ်: Complex logic တွေကို ရှင်းပြနိုင်တယ်
Documentation: Function/Method က ဘာလုပ်တာလဲ မှတ်တမ်းတင်နိုင်တယ်
Team collaboration: အခြား developers တွေ code နားလည်အောင် ကူညီပေးတယ်
Debugging: Code အပိုင်းတစ်ခုကို ယာယီ ပိတ်ထားလို့ ရတယ် (comment out)
Reminders: TODO, FIXME စတဲ့ မှတ်သားရမည့် အရာတွေ မှတ်ထားလို့ ရတယ်

Key Point: Comments က program ရဲ့ behavior ကို မပြောင်းပါ။ Compiler က ignore လုပ်လို့ output မှာ သက်ရောက်မှု မရှိပါ။

💬

Single-Line

Short comments on one line using //

📝

Multi-Line

Longer comments spanning multiple lines using /* */

📚

Documentation

Special comments for API docs using /** */

2. Single-Line Comments (တစ်ကြောင်းတည်း မှတ်ချက်)

Single-line comments start with // and continue to the end of the line. Everything after // is ignored by the compiler.

Java - SingleLineExample.java

public class SingleLineExample {
    public static void main(String[] args) {
        // This is a single-line comment
        System.out.println("Hello, World!");
        
        // Print the current year
        System.out.println("Year: 2024");
        
        int age = 25;  // Variable to store age
        
        // Calculate next year's age
        int nextAge = age + 1;
        System.out.println("Next year: " + nextAge);  // Output: 26
    }
}

Output

Hello, World!
Year: 2024
Next year: 26

အသုံးပြုနည်း အသေးစိတ်

Syntax: // နဲ့ စပါတယ်။ Double forward slashes သုံးပါတယ်။

Usage patterns:

Above the code: Code အပေါ်မှာ comment ထည့်ပြီး ဘာလုပ်မယ် ဆိုတာ ရှင်းပြပါ
```
// Calculate total price
int total = price * quantity;
```
End of line: Code ရဲ့ အဆုံးမှာ comment ထည့်ပြီး ရှင်းလင်းချက် ပေးပါ
```
int age = 18;  // Legal age for voting
```
Standalone line: သီးခြား line တစ်ကြောင်းလုံး comment အဖြစ် သုံးပါ
```
// This section handles user authentication
```

ဘယ်အချိန်မှာ သုံးသင့်လဲ?

တိုတောင်းတဲ့ ရှင်းလင်းချက်တွေ အတွက်
Variable/constant ရဲ့ purpose ရှင်းပြချင်တဲ့ အခါ
Code တစ်ကြောင်း သို့မဟုတ် နှစ်ကြောင်း အကြောင်း ရှင်းပြချင်တဲ့ အခါ
TODO, FIXME markers ထည့်ချင်တဲ့ အခါ

📌 အရေးကြီးတဲ့ စည်းမျဉ်း: // နောက်က အရာအားလုံး comment ဖြစ်ပါတယ် (same line မှာ)။ Next line က ပုံမှန် code ပြန်ဖြစ်ပါတယ်။

Commenting Out Code (Code ကို ယာယီ ပိတ်ထားခြင်း)

Java

public class DebugExample {
    public static void main(String[] args) {
        System.out.println("Program started");
        
        // Temporarily disabled for testing
        // System.out.println("Debug info");
        // int debugValue = 100;
        
        System.out.println("Program ended");
    }
}

Commenting Out ရဲ့ အသုံးဝင်ပုံ

Debugging: Code အပိုင်းတစ်ခုကို ယာယီ ပိတ်ပြီး ပြဿနာ ရှာချင်တဲ့ အခါ သုံးပါတယ်။ Code ကို delete မလုပ်ဘဲ comment out လုပ်ထားလို့ နောက်မှ ပြန်ဖွင့်လို့ ရပါတယ်။

Testing alternatives: Code ရဲ့ different versions တွေကို စမ်းချင်တဲ့ အခါ old code ကို comment out လုပ်ပြီး new code ရေးနိုင်ပါတယ်။

⚠️ Warning: Commented code ကို production မှာ မထားသင့်ပါ။ Debugging ပြီးရင် ဖျက်ပစ်ပါ။

3. Multi-Line Comments (များကြောင်း မှတ်ချက်)

Multi-line comments start with /* and end with */. Everything between these markers is ignored by the compiler, even if it spans multiple lines.

Java - MultiLineExample.java

public class MultiLineExample {
    public static void main(String[] args) {
        /*
         * This is a multi-line comment
         * It can span multiple lines
         * Compiler ignores everything between /* and */
         */
        System.out.println("Hello!");
        
        /* 
           Calculate the area of a rectangle
           Formula: length * width
           Author: Your Name
           Date: 2024-01-15
        */
        int length = 10;
        int width = 5;
        int area = length * width;
        System.out.println("Area: " + area);
        
        /* This can also be on a single line */
        int x = 100;
    }
}

Output

Hello!
Area: 50

အသုံးပြုနည်း အသေးစိတ်

Syntax:

Start: /*
End: */
အကြားက အရာအားလုံး comment ဖြစ်ပါတယ်

Common formatting styles:

/* Simple style */

/*
 * Asterisk-aligned style
 * Second line
 * Third line
 */

/* 
   Indented style
   Second line
   Third line
*/

ဘယ်အချိန်မှာ သုံးသင့်လဲ?

Long descriptions: Complex logic ကို အသေးစိတ် ရှင်းပြချင်တဲ့ အခါ
File headers: File information, copyright, author details တွေ ထည့်တဲ့ အခါ
Algorithm explanations: Step-by-step process တွေ document လုပ်တဲ့ အခါ
Temporary disabling: Code block ကြီးကို ယာယီ ပိတ်ထားချင်တဲ့ အခါ

⚠️ Warning: Multi-line comments တွေက nested (တစ်ခုအတွင်းမှာ တစ်ခု) လုပ်လို့ မရပါ!

/* Outer comment
   /* Inner comment - THIS WILL CAUSE ERROR! */
*/

Commenting Out Code Blocks

Java

public class Example {
    public static void main(String[] args) {
        System.out.println("Active code");
        
        /*
        // Disabled feature
        int oldCalculation = 10 * 20;
        System.out.println("Old way: " + oldCalculation);
        
        // More disabled code
        for (int i = 0; i < 5; i++) {
            System.out.println(i);
        }
        */
        
        // New implementation
        int newCalculation = 15 * 20;
        System.out.println("New way: " + newCalculation);
    }
}

Use Cases

Multi-line comments က code block များများ ပိတ်ချင်တဲ့ အခါ အဆင်ပြေပါတယ်။ Single-line comments နဲ့ ပိတ်ရင် line တစ်ကြောင်းချင်းစီ // ထည့်ရလို့ ပိုပင်ပန်းပါတယ်။

Multi-line comments အတွင်းမှာ single-line comments တွေ ပါနိုင်ပါတယ်။ ဒါပေမယ့် multi-line comments nested မလုပ်နိုင်တာ သတိထားပါ။

4. Documentation Comments (Javadoc)

Documentation comments are special comments that start with /** and end with */. They are used to generate API documentation automatically using the javadoc tool.

Java - JavadocExample.java

/**
 * This class demonstrates Javadoc comments.
 * It provides methods for basic arithmetic operations.
 * 
 * @author Your Name
 * @version 1.0
 * @since 2024-01-15
 */
public class Calculator {
    
    /**
     * Adds two integers and returns the result.
     * 
     * @param a the first integer
     * @param b the second integer
     * @return the sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
    
    /**
     * Subtracts the second integer from the first.
     * 
     * @param a the first integer (minuend)
     * @param b the second integer (subtrahend)
     * @return the difference of a and b
     * @throws IllegalArgumentException if b is greater than a
     */
    public int subtract(int a, int b) {
        if (b > a) {
            throw new IllegalArgumentException("b cannot be greater than a");
        }
        return a - b;
    }
    
    /**
     * Calculates the area of a rectangle.
     * 
     * This method multiplies length and width to get the area.
     * Both parameters must be positive.
     * 
     * @param length the length of the rectangle
     * @param width the width of the rectangle
     * @return the area of the rectangle
     * @see #calculatePerimeter(int, int)
     */
    public int calculateArea(int length, int width) {
        return length * width;
    }
    
    /**
     * Calculates the perimeter of a rectangle.
     * 
     * @param length the length of the rectangle
     * @param width the width of the rectangle
     * @return the perimeter of the rectangle
     * @see #calculateArea(int, int)
     */
    public int calculatePerimeter(int length, int width) {
        return 2 * (length + width);
    }
}

Javadoc အကြောင်း အသေးစိတ်

Syntax: /** နဲ့ start လုပ်ပြီး */ နဲ့ end ဖြစ်ပါတယ်။ Multi-line comment နဲ့ ဆင်တယ်၊ ဒါပေမယ့် extra asterisk (*) တစ်ခု ပိုပါတယ်။

Common Javadoc Tags:

@author - Code ရေးသူ အမည်
@version - Version number
@since - ဘယ် version/date မှာ စတင် ထည့်သွင်းခဲ့လဲ
@param - Method parameter ရှင်းလင်းချက်
@return - Return value ရှင်းလင်းချက်
@throws / @exception - Exception တွေ ဖြစ်နိုင်တာ ရှင်းပြတယ်
@see - Related methods/classes တွေ ညွှန်းပြတယ်
@deprecated - အဲ့ဒီ method/class က outdated ဖြစ်ပြီဆိုတာ mark လုပ်တယ်

ဘာကြောင့် အရေးကြီးလဲ?

Professional documentation: javadoc tool က HTML documentation ကို automatically generate လုပ်ပေးပါတယ်
IDE support: Modern IDEs တွေက Javadoc ကို ဖတ်ပြီး tooltips, autocomplete မှာ information ပြပါတယ်
API documentation: Library developers တွေ သုံးတဲ့ standard format ပါ
Team collaboration: Method/class က ဘာလုပ်တယ်ဆိုတာ ပြတ်ပြတ်သားသား သိစေပါတယ်

Generating documentation:

javadoc Calculator.java

ဒါက HTML files တွေ generate လုပ်ပေးမှာပါ။ Browser နဲ့ ဖွင့်ကြည့်လို့ ရပါတယ်။

Class-Level vs Method-Level Javadoc

Java

/**
 * Represents a student in the school system.
 * This class stores student information and provides
 * methods to manage student data.
 * 
 * @author School Admin
 * @version 2.0
 */
public class Student {
    
    /** Student's unique ID number */
    private int studentId;
    
    /** Student's full name */
    private String name;
    
    /**
     * Creates a new Student with the given ID and name.
     * 
     * @param studentId unique identifier for the student
     * @param name full name of the student
     */
    public Student(int studentId, String name) {
        this.studentId = studentId;
        this.name = name;
    }
    
    /**
     * Gets the student's ID.
     * 
     * @return the student's unique ID number
     */
    public int getStudentId() {
        return studentId;
    }
    
    /**
     * Gets the student's name.
     * 
     * @return the student's full name
     */
    public String getName() {
        return name;
    }
}

ဘယ်နေရာမှာ သုံးသင့်လဲ?

Class level: Class ရဲ့ purpose, version, author တွေ document လုပ်ပါ
Method level: Method ရဲ့ functionality, parameters, return value, exceptions တွေ document လုပ်ပါ
Field level: Important instance variables တွေကို ရှင်းပြပါ (တိုတောင်းရင် /** */ one-liner သုံးလို့ ရပါတယ်)
Constructor level: Constructor parameters တွေနဲ့ initialization logic ကို ရှင်းပြပါ

📌 Public APIs, libraries, frameworks တွေမှာ Javadoc က မဖြစ်မနေ ထည့်သင့်ပါတယ်။

5. Comment Best Practices (အကောင်းဆုံး အလေ့အကျင့်များ)

✅ Good Comment Practices1. Explain WHY, not WHAT
                            // ❌ Bad: Explains what (obvious from code)
int age = 25;  // Set age to 25

// ✅ Good: Explains why
int age = 25;  // Minimum age required for insurance eligibility
                        
2. Keep comments updated
                            // ❌ Bad: Outdated comment
// Calculate discount as 10%
double discount = price * 0.20;  // Actually 20% now!

// ✅ Good: Accurate comment
// Calculate discount as 20% for premium members
double discount = price * 0.20;
                        
3. Use comments for complex logic
                            // ✅ Good: Explains complex algorithm
// Binary search algorithm - O(log n) time complexity
// Divides search space in half each iteration
int mid = (low + high) / 2;
                        
4. Add TODO and FIXME markers
                            // TODO: Implement input validation
// FIXME: Bug when input is negative
// NOTE: This method is performance-critical
// HACK: Temporary workaround until API is fixed
                        
5. Comment public APIs
                            /**
 * ✅ Good: Complete documentation for public method
 * Validates user email format.
 * 
 * @param email the email address to validate
 * @return true if valid, false otherwise
 */
public boolean validateEmail(String email) {
    // Implementation
    return email.contains("@");
}
                        

⚠️ Bad Comment Practices (ရှောင်ကြဉ်သင့်တာများ)

1. Stating the obvious

// ❌ Bad: Obvious from code
int x = 10;  // Assign 10 to x
x++;  // Increment x by 1

2. Commented-out code without explanation

// ❌ Bad: No context
// int oldValue = 100;
// System.out.println(oldValue);

// ✅ Better: Explain why commented
// Old implementation - removed after performance testing
// Keeping for reference until version 2.0 release
// int oldValue = 100;

3. Redundant comments

// ❌ Bad: Comment repeats method name
/**
 * Gets the name.
 * @return the name
 */
public String getName() {
    return name;
}

// ✅ Better: Add value
/**
 * Returns the user's full name including middle initial if available.
 * @return formatted full name
 */
public String getName() {
    return name;
}

4. Excessive comments

// ❌ Bad: Too many obvious comments
public void calculateTotal() {
    // Declare variable for price
    int price = 100;
    // Declare variable for quantity
    int quantity = 5;
    // Multiply price and quantity
    int total = price * quantity;
    // Print the total
    System.out.println(total);
}

// ✅ Better: One meaningful comment
public void calculateTotal() {
    // Calculate order total with current pricing
    int total = 100 * 5;
    System.out.println(total);
}

Golden Rules (ရွှေစည်းမျဉ်းများ)

Write self-documenting code first: Variable/method names ကို ရှင်းရှင်းလင်းလင်း ပေးပါ။ Comment မလိုအောင် code က clear ဖြစ်သင့်ပါတယ်
Comment the "why", not the "what": Code က "what" ကို ပြနေပြီးသား။ Comment က "why" ကို ရှင်းပြပါ
Keep comments concise: တိုတောင်းပြီး သဘောပေါက်လွယ်အောင် ရေးပါ
Update comments when code changes: Code ပြောင်းရင် comment ကိုလည်း update လုပ်ပါ
Remove unused commented code: Production မှာ commented code မထားပါနဲ့
Use Javadoc for public APIs: Public methods/classes တွေမှာ Javadoc သုံးပါ

6. Key Takeaways (မှတ်သားရမည့် အချက်များ)

Single-line comments: // - Short, one-line explanations
Multi-line comments: /* */ - Longer explanations spanning multiple lines
Documentation comments: /** */ - Javadoc for generating API documentation
Comments are ignored by compiler - No effect on program execution
Explain WHY, not WHAT - Code shows what, comments explain why
Keep comments updated - Outdated comments are worse than no comments
Use Javadoc for public APIs - Essential for libraries and frameworks
Avoid obvious comments - Don't state what's clear from code
Use TODO/FIXME markers - Track work that needs to be done
Self-documenting code is best - Clear names reduce need for comments

💡 Practice Exercise

Task: Add appropriate comments to this code:

Java - Before

public class Circle {
    private double radius;
    
    public Circle(double radius) {
        this.radius = radius;
    }
    
    public double calculateArea() {
        return 3.14159 * radius * radius;
    }
    
    public double calculateCircumference() {
        return 2 * 3.14159 * radius;
    }
}

Add:

Class-level Javadoc comment
Constructor Javadoc comment
Method Javadoc comments with @param and @return tags
Inline comment explaining the formulas

💡 Quick Quiz

Q1: Which comment type is used for generating API documentation?

// Single-line comment /* Multi-line comment */ /** Javadoc comment */

Q2: Are comments compiled into bytecode?

Yes, all comments are compiled No, compiler ignores all comments Only Javadoc comments are compiled

Q3: What should comments primarily explain?

What the code does Why the code does it How to run the code

Java Comments

1. Comments ဆိုတာ ဘာလဲ?

Single-Line

Multi-Line

Documentation

2. Single-Line Comments (တစ်ကြောင်းတည်း မှတ်ချက်)

Commenting Out Code (Code ကို ယာယီ ပိတ်ထားခြင်း)

3. Multi-Line Comments (များကြောင်း မှတ်ချက်)

Commenting Out Code Blocks

4. Documentation Comments (Javadoc)

Class-Level vs Method-Level Javadoc

5. Comment Best Practices (အကောင်းဆုံး အလေ့အကျင့်များ)

✅ Good Comment Practices

1. Explain WHY, not WHAT

2. Keep comments updated

3. Use comments for complex logic

4. Add TODO and FIXME markers

5. Comment public APIs

⚠️ Bad Comment Practices (ရှောင်ကြဉ်သင့်တာများ)

1. Stating the obvious

2. Commented-out code without explanation

3. Redundant comments

4. Excessive comments

6. Key Takeaways (မှတ်သားရမည့် အချက်များ)

💡 Practice Exercise

💡 Quick Quiz

Your Notes