Longer description of class behavior, responsibilities, and usage. * Use paragraph tags to separate paragraphs. Can include HTML formatting. * *
Additional paragraphs as needed to fully describe the class, * including design patterns, thread safety, or important implementation * details. * *
{@code
* ClassName obj = new ClassName(param);
* obj.method();
* }
*
* @author Author Name
* @version 1.0
* @since 1.0
* @see RelatedClass
*/
public class ClassName {
}
```
#### Method Javadoc
```java
/**
* Brief one-line summary of what method does.
*
* 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 ```java /** * Brief description of field purpose. * *
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:
```java
/**
* @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 External reference
* @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
```java
// 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
```java
// GOOD: Explain WHY
// Use HashMap for O(1) lookup performance - critical for this hot path
Map Supported formats:
* Example usage:
* 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:
```python
# 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:
```python
# 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:
```python
# 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
```java
// 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
```python
# 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:
```python
# ============================================================================
# Database Operations
# ============================================================================
def save_user(user):
pass
def delete_user(user_id):
pass
# ============================================================================
# Email Operations
# ============================================================================
def send_email(to, subject, body):
pass
```
```java
// ========================================================================
// Constructors
// ========================================================================
public ClassName() {
}
// ========================================================================
// Public Methods
// ========================================================================
public void method() {
}
```
### 7. Document Complex Regular Expressions
```python
# 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
```python
# 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
```python
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:
```python
"""
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.
*
*
*
*
*/
```
**2. Link to related code:**
```java
/**
* Processes user input.
*
* @see UserValidator#validate(String)
* @see #processInternal(User)
* @see API Documentation
*/
```
**3. Include code examples:**
```java
/**
* Calculates discount based on quantity.
*
* {@code
* double price = 100.0;
* int quantity = 10;
* double discount = calculator.calculateDiscount(price, quantity);
* // Returns 90.0 (10% discount for bulk order)
* }
*/
```
**4. Document thread safety:**
```java
/**
* Thread-safe cache implementation.
*
*