Comment Style Guides

Comment Style Guides

Language-specific comment conventions and best practices for Python and Java.

Table of Contents

1. Python Style Guide
2. Java Style Guide
3. General Best Practices

Python Style Guide

Documentation Strings (Docstrings)

Python uses docstrings for documenting modules, classes, and functions. Follow PEP 257 conventions.

Module Docstrings

"""
User authentication and authorization module.

This module provides functions for user login, logout, password management,
and permission checking. Uses JWT tokens for stateless authentication.

Example:
    from auth import authenticate, check_permission

    user = authenticate(username, password)
    if check_permission(user, 'admin'):
        perform_admin_action()
"""

Function Docstrings - Google Style

def function_name(param1: str, param2: int) -> bool:
    """
    Brief one-line summary of what function does.

    Optional longer description that provides more detail about the
    function's behavior, algorithms used, or important considerations.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Description of return value

    Raises:
        ValueError: When param2 is negative
        TypeError: When param1 is not a string

    Example:
        >>> function_name("test", 42)
        True

    Note:
        Any important notes or caveats about usage
    """

Function Docstrings - NumPy Style

def function_name(param1: str, param2: int) -> bool:
    """
    Brief one-line summary of what function does.

    Optional longer description that provides more detail.

    Parameters
    ----------
    param1 : str
        Description of first parameter
    param2 : int
        Description of second parameter

    Returns
    -------
    bool
        Description of return value

    Raises
    ------
    ValueError
        When param2 is negative

    Examples
    --------
    >>> function_name("test", 42)
    True

    Notes
    -----
    Any important notes or caveats
    """

Class Docstrings

class ClassName:
    """
    Brief one-line summary of class purpose.

    Longer description of what the class does, its responsibility,
    and how it should be used. Mention any design patterns or
    important implementation details.

    Attributes:
        attribute1: Description of attribute1
        attribute2: Description of attribute2

    Example:
        >>> obj = ClassName(param)
        >>> obj.method()
        'result'

    Note:
        Any important usage notes or warnings
    """

    def __init__(self, param):
        """
        Initialize ClassName instance.

        Args:
            param: Description of initialization parameter
        """

Inline Comments

Comment Style

# Single-line comments use hash and space
# Multiple single-line comments for longer explanations
# Continue on new lines as needed

# Leave blank line before comment block for readability
def function():
    pass

When to Use Inline Comments

# GOOD: Explain WHY, not WHAT
# Use binary search because list is pre-sorted and may contain millions of items
result = binary_search(items, target)

# BAD: Obvious comment
# Call binary search function
result = binary_search(items, target)

# GOOD: Explain business logic
# Free shipping for orders over $50 (marketing promotion until Q4 2024)
if order_total > 50:
    shipping_cost = 0

# GOOD: Explain workaround
# HACK: Add delay to work around rate limiting bug in API v1.2
# Remove when upgrading to v2.0 (scheduled for March 2024)
time.sleep(0.1)

Type Hints

Type hints reduce the need for comments by making code self-documenting:

# Without type hints - needs comment
def process_users(users, active):
    """Process users. active filters for active users only."""
    pass

# With type hints - self-documenting
def process_users(users: List[User], active: bool) -> List[User]:
    """Process user list, optionally filtering by active status."""
    pass

TODOs and Annotations

# TODO: Add email validation
# Format: TODO: Brief description of what needs to be done

# FIXME: This breaks when input is None
# Format: FIXME: Description of the bug

# XXX: Questionable code that works but needs review
# Format: XXX: Description of the concern

# HACK: Workaround for library bug #123
# Format: HACK: Description and reason for workaround

# NOTE: Important information about implementation
# Format: NOTE: The information

# OPTIMIZE: This could be faster with caching
# Format: OPTIMIZE: Suggestion for optimization

PEP 8 Comment Guidelines

• Limit line length to 72 characters for comments
• Use complete sentences with proper capitalization
• Use two spaces after sentence-ending period (optional but recommended)
• Block comments generally consist of paragraphs built from complete sentences
• Each sentence in block comments should end with a period

Java Style Guide

Javadoc Comments

Java uses Javadoc comments for API documentation. Start with /** and include structured tags.

Class Javadoc

/**
 * Brief one-line summary of class purpose.
 *
 * <p>Longer description of class behavior, responsibilities, and usage.
 * Use paragraph tags to separate paragraphs. Can include HTML formatting.
 *
 * <p>Additional paragraphs as needed to fully describe the class,
 * including design patterns, thread safety, or important implementation
 * details.
 *
 * <h3>Usage Example:</h3>
 * <pre>{@code
 * ClassName obj = new ClassName(param);
 * obj.method();
 * }</pre>
 *
 * @author Author Name
 * @version 1.0
 * @since 1.0
 * @see RelatedClass
 */
public class ClassName {
}

Method Javadoc

/**
 * Brief one-line summary of what method does.
 *
 * <p>Optional longer description providing more detail about behavior,
 * algorithms, or important considerations.
 *
 * @param param1 description of first parameter
 * @param param2 description of second parameter
 * @return description of return value
 * @throws IllegalArgumentException if param1 is null
 * @throws IOException if file cannot be read
 * @see #relatedMethod(String)
 * @since 1.5
 */
public String methodName(String param1, int param2)
        throws IllegalArgumentException, IOException {
    return "";
}

Field Javadoc

/**
 * Brief description of field purpose.
 *
 * <p>Longer explanation if needed, including valid values,
 * constraints, or important usage notes.
 */
private String fieldName;

/** Brief description for simple fields (one-liner acceptable). */
private static final int MAX_SIZE = 100;

Javadoc Tags

Common Javadoc tags and their usage:

/**
 * @param paramName Description of parameter
 * @return Description of return value
 * @throws ExceptionType When and why this exception is thrown
 * @see ClassName For related information
 * @see #methodName(Type) For related method
 * @see <a href="URL">External reference</a>
 * @since version Version when this was added
 * @deprecated Explanation and alternative to use
 * @author Author name (usually for classes)
 * @version Version number (usually for classes)
 */

Inline Comments

// Single-line comments use double slash and space
// Multiple lines continue on new lines

/*
 * Multi-line comments use this format
 * with asterisks on each line for readability
 */

/* Single-line multi-line comment also valid */

When to Comment

// GOOD: Explain WHY
// Use HashMap for O(1) lookup performance - critical for this hot path
Map<String, User> userCache = new HashMap<>();

// BAD: State the obvious
// Create a new HashMap
Map<String, User> userCache = new HashMap<>();

// GOOD: Explain business logic
// Orders over $50 qualify for free shipping (marketing policy Q4 2024)
if (orderTotal > 50.00) {
    shippingCost = 0.0;
}

// GOOD: Document workarounds
// HACK: Sleep to avoid connection pool bug in driver v1.5
// Remove when upgrading to v2.0 (scheduled March 2024)
Thread.sleep(100);

TODOs and Annotations

// TODO: Add input validation
// Format: TODO: Description of what needs doing

// FIXME: NullPointerException when user is null
// Format: FIXME: Description of bug

// HACK: Workaround for library bug #456
// Format: HACK: Description and reason

// NOTE: This must be called before init()
// Format: NOTE: Important information

// @deprecated Use {@link #newMethod()} instead. Scheduled for removal in v3.0.
@Deprecated
public void oldMethod() {
}

Javadoc Best Practices

1. Use HTML formatting:

/**
 * Process items in the following order:
 * <ol>
 *   <li>Validate input
 *   <li>Transform data
 *   <li>Save to database
 * </ol>
 *
 * <p>Supported formats:
 * <ul>
 *   <li>JSON
 *   <li>XML
 *   <li>CSV
 * </ul>
 */

2. Link to related code:

/**
 * Processes user input.
 *
 * @see UserValidator#validate(String)
 * @see #processInternal(User)
 * @see <a href="https://docs.example.com/api">API Documentation</a>
 */

3. Include code examples:

/**
 * Calculates discount based on quantity.
 *
 * <p>Example usage:
 * <pre>{@code
 * double price = 100.0;
 * int quantity = 10;
 * double discount = calculator.calculateDiscount(price, quantity);
 * // Returns 90.0 (10% discount for bulk order)
 * }</pre>
 */

4. Document thread safety:

/**
 * Thread-safe cache implementation.
 *
 * <p>All methods are synchronized and safe for concurrent access
 * from multiple threads. However, iterating over entries requires
 * external synchronization.
 *
 * @see java.util.concurrent.ConcurrentHashMap for lock-free alternative
 */

General Best Practices

1. Write Comments for the Reader

Comments should help future maintainers understand the code:

# POOR: Cryptic abbreviation
# Calc ttl amt w/ disc
total = calculate_total(items, discount)

# GOOD: Clear explanation
# Calculate total price including 15% volume discount for bulk orders
total = calculate_total(items, discount=0.15)

2. Keep Comments Updated

Outdated comments are worse than no comments:

# BAD: Comment doesn't match code
# Return user age in years
return user.birth_date  # Actually returns birth_date, not age!

# GOOD: Accurate comment
# Return user's birth date for age calculation
return user.birth_date

3. Use Consistent Terminology

Match the language of your domain:

# If your domain uses "customer", don't say "user" in comments
# INCONSISTENT:
def get_customer(customer_id):
    """Retrieve user by ID."""  # Says "user"

# CONSISTENT:
def get_customer(customer_id):
    """Retrieve customer by ID."""  # Says "customer"

4. Don't Comment Bad Code - Rewrite It

// BAD: Commenting messy code
// This is messy but necessary because of edge cases
if ((x > 0 && y < 10 && (z == 5 || z == 7) && !flag) ||
    (x < 0 && special)) {
    doSomething();
}

// GOOD: Refactor instead
private boolean shouldDoSomething(int x, int y, int z,
                                 boolean flag, boolean special) {
    boolean normalCase = x > 0 && y < 10 &&
                        (z == 5 || z == 7) && !flag;
    boolean specialCase = x < 0 && special;
    return normalCase || specialCase;
}

if (shouldDoSomething(x, y, z, flag, special)) {
    doSomething();
}

5. Avoid Noise Comments

# BAD: Adds no value
i = 0  # Set i to zero
i += 1  # Increment i
return True  # Return true

# GOOD: Only comment non-obvious code
# Reset cursor to beginning of file
file.seek(0)

6. Use Comments to Mark Sections

For large files, section comments help navigation:

# ============================================================================
# Database Operations
# ============================================================================

def save_user(user):
    pass

def delete_user(user_id):
    pass


# ============================================================================
# Email Operations
# ============================================================================

def send_email(to, subject, body):
    pass

// ========================================================================
// Constructors
// ========================================================================

public ClassName() {
}


// ========================================================================
// Public Methods
// ========================================================================

public void method() {
}

7. Document Complex Regular Expressions

# Email validation regex (RFC 5322 simplified):
# ^[a-zA-Z0-9._%+-]+  - Local part (before @)
# @                   - Literal @ symbol
# [a-zA-Z0-9.-]+      - Domain name
# \.                  - Literal dot
# [a-zA-Z]{2,}$       - Top-level domain (min 2 chars)
EMAIL_PATTERN = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'

8. Explain Magic Numbers

# BAD: Unexplained constant
if temperature > 273.15:
    status = "above_freezing"

# GOOD: Explained constant
WATER_FREEZING_POINT_KELVIN = 273.15
if temperature > WATER_FREEZING_POINT_KELVIN:
    status = "above_freezing"

9. Document Assumptions

def calculate_tax(amount):
    """
    Calculate sales tax on amount.

    Assumes:
    - Amount is in USD
    - Tax rate is for California (7.25%)
    - No special tax exemptions apply

    Args:
        amount: Purchase amount in dollars

    Returns:
        Tax amount in dollars
    """
    CA_TAX_RATE = 0.0725
    return amount * CA_TAX_RATE

10. Use Diagrams When Helpful

For complex flows, consider ASCII art:

"""
Authentication Flow:
┌──────┐     ┌──────┐     ┌────────┐
│Client│────▶│Server│────▶│Database│
└──────┘     └──────┘     └────────┘
   │            │              │
   │  username  │              │
   │  password  │              │
   │───────────▶│              │
   │            │   verify     │
   │            │─────────────▶│
   │            │              │
   │            │◀─────────────│
   │   token    │              │
   │◀───────────│              │
"""

11. When in Doubt, Err on the Side of Clarity

If you're unsure whether to add a comment, consider:

• Will this be obvious to someone seeing this code for the first time?
• Will I understand this in 6 months?
• Does this follow a common pattern that needs no explanation?

When in doubt, add the comment. It's easier to remove unnecessary comments during review than to debug unclear code later.