Java Comments & Industry Naming Conventions
Single-line // ยท Multi-line /* */ ยท Javadoc /** */ with Tags ยท Naming Conventions (PascalCase, camelCase, UPPER_SNAKE_CASE) ยท Self-Documenting Code
Mastering clean code standards in Java: the three types of comments including professional Javadoc generation with standard tags (@param, @return, @throws), and the official industry naming conventions used across enterprise software teams.
1. The 3 Types of Comments in Java
Comments are explanatory notes placed inside source code to assist human developers. The Java compiler completely ignores comments during compilation, meaning they have zero impact on binary size or runtime execution performance.
1. Single-Line Comments (//)
Used for short, inline explanations of complex algorithms or quick notes:
// Calculate the compound annual growth rate (CAGR)
double cagr = Math.pow(finalValue / initialValue, 1.0 / years) - 1;2. Multi-Line Comments (/* ... */)
Used for paragraph-length documentation or temporarily disabling code blocks during debugging:
/*
* The following algorithm implements the Luhn checksum
* to validate credit card account numbers before
* initiating payment gateway network requests.
*/3. Javadoc Comments (/** ... */)
Professional documentation comments placed immediately above classes, interfaces, methods, and fields. The JDK tool javadoc parses these comments into rich HTML documentation pages (the same documentation you read on Oracle's official Java API website!):
/**
* Calculates the total order price including state tax and shipping fees.
*
* @param basePrice The subtotal price before tax (must be > 0).
* @param taxRate The applicable state sales tax percentage (e.g. 0.08 for 8%).
* @return The final rounded invoice amount.
* @throws IllegalArgumentException If basePrice is negative.
*/
public double calculateInvoice(double basePrice, double taxRate) {
if (basePrice < 0) throw new IllegalArgumentException("Base price cannot be negative");
return basePrice + (basePrice * taxRate);
}2. Standard Javadoc Tags
Professional Java teams use standard Javadoc tags to build enterprise API documentation:
| Tag | Syntax | Description |
|---|---|---|
| **`@author`** |
@author Developer Name | Specifies the author/team responsible for creating the class. |
| @version | @version 1.0.0 | Documents the current software version release. |
| @param | @param parameterName description | Documents the purpose, type, and constraints of a method parameter. |
| @return | @return description | Documents the return value and meaning of the method output. |
| @throws | @throws ExceptionClass condition | Documents which exceptions can be thrown and under what conditions. |
| @see | @see ClassName#method | Provides a cross-reference link to related classes or documentation. |
| @deprecated| @deprecated reason and replacement | Warns developers that a method is obsolete and will be removed in future versions. |
3. Official Java Naming Conventions
Java has strict, universally accepted naming conventions established by Oracle and Google Style Guides. Adhering to these standards is essential for professional code readability:
| Code Element | Naming Convention | Example | Rules & Guidelines |
|---|---|---|---|
| **Classes & Interfaces** |
BankAccount, PaymentService, UserRepository | Must begin with an uppercase letter; nouns representing entities. |
| Methods | camelCase (lowerCamelCase) | calculateTotal(), sendNotification(), getUserById() | Must begin with a lowercase letter; verbs representing actions. |
| Variables & Fields | camelCase (lowerCamelCase) | accountBalance, userEmail, totalPrice | Must begin with a lowercase letter; descriptive nouns. |
| Constants | UPPERSNAKECASE | MAX_RETRY_ATTEMPTS, DEFAULT_TIMEOUT_MS, PI | All uppercase letters separated by underscores; declared static final. |
| Packages | all lowercase (reverse domain) | com.ourcompiler.service, org.springframework.boot | Unique reverse Internet domain name prefix; all lowercase. |
| Generics Type Parameters | Single Uppercase Letter | T (Type), E (Element), K (Key), V (Value) | Single capital letters. |
Beginner Example & Code Anatomy
/**
* Demonstrates clean coding standards, Javadoc annotations,
* and official Java naming conventions.
*
* @author Our Compiler Technical Editorial Team
* @version 2026.1
*/
public class Main {
// Constant in UPPER_SNAKE_CASE
public static final double DEFAULT_TAX_RATE = 0.18;
public static final String CURRENCY_SYMBOL = "INR (โน)";
/**
* Computes the total billing amount after applying standard tax.
*
* @param itemPrice Subtotal price of purchased goods.
* @return Final amount including applicable tax.
*/
public static double computeBill(double itemPrice) {
// Single-line comment: calculate gross total
double taxAmount = itemPrice * DEFAULT_TAX_RATE;
return itemPrice + taxAmount;
}
public static void main(String[] args) {
double productPrice = 2500.00; // Variable in camelCase
double totalPayable = computeBill(productPrice);
System.out.println("Product Price : โน" + productPrice);
System.out.println("Tax Rate : " + (DEFAULT_TAX_RATE * 100) + "%");
System.out.println("Total Invoice : โน" + totalPayable);
System.out.println("Currency Code : " + CURRENCY_SYMBOL);
}
}
๐ Line-by-Line Code Explanation
/** ... */
Javadoc documentation block containing structured metadata for the class and its methods.
public static final double DEFAULT_TAX_RATE = 0.18;
Constant declared with static final modifiers formatted in UPPER_SNAKE_CASE.
double taxAmount = itemPrice * DEFAULT_TAX_RATE;
Local variable in camelCase representing intermediate calculation.
computeBill(productPrice)
Method invocation in camelCase conveying clear action verb.
Practical Real-World Example
/**
* Represents an employee record with enterprise naming conventions.
*/
class EmployeeRecord {
// Instance variables in camelCase
private String employeeName;
private int employeeId;
private double monthlySalary;
public EmployeeRecord(String employeeName, int employeeId, double monthlySalary) {
this.employeeName = employeeName;
this.employeeId = employeeId;
this.monthlySalary = monthlySalary;
}
public double calculateAnnualCTC() {
// 12 months salary + 10% standard enterprise performance bonus
final double BONUS_PERCENTAGE = 0.10;
double annualBase = this.monthlySalary * 12;
return annualBase + (annualBase * BONUS_PERCENTAGE);
}
public void printSummary() {
System.out.println("Employee ID : #" + employeeId);
System.out.println("Employee Name : " + employeeName);
System.out.println("Annual CTC : โน" + calculateAnnualCTC());
}
}
public class Main {
public static void main(String[] args) {
EmployeeRecord dev = new EmployeeRecord("Balaji Nayak", 10142, 85000.00);
dev.printSummary();
}
}
- Using lowercase for class names: "class bankAccount" violates Java conventions and makes code hard to distinguish from variables.
- Using underscores in variable names: "int user_age" is C/Python style; in Java, always use camelCase: "int userAge".
- Over-commenting obvious code: Writing "// print hello" above "System.out.println("hello")" adds noise. Comments should explain WHY a complex logic exists, not WHAT simple syntax does.
- Naming constants in lowercase: Writing "final double pi = 3.14" violates conventions; write "final double PI = 3.14159".
Test your understanding by writing the code directly in your editor or running in our online Java compiler:
// Coding Challenge:
// Refactor the following poorly formatted code to follow official Java naming conventions:
// - Class name: employee_manager -> ???
// - Constant: max_limit = 500 -> ???
// - Variable: User_first_Name -> ???
// - Method: Calculate_Salary() -> ???
public class Main {
public static void main(String[] args) {
// TODO: Implement the refactored code following standard Java naming conventions
}
}
๐ก Frequently Asked Questions & Interview Insights
โ How do I generate HTML documentation from Javadoc comments?
Run the command "javadoc -d docs Main.java" in your terminal. The JDK will automatically generate a complete web portal with clickable class indexes and API reference pages.
โ Can variable names start with numbers or special characters in Java?
Variable names CANNOT start with a digit (e.g. "1stName" is invalid). They can only start with a letter (a-z, A-Z), an underscore (_), or a dollar sign ($).
โ Are comments included in the compiled .class file?
No. The Java compiler strips out all single-line and multi-line comments during the parsing phase. Javadoc comments are optionally preserved in class metadata only if specific retention flags are enabled.
๐ Quick Chapter Recap
- Java supports single-line (//), multi-line (/* */), and Javadoc (/** */) comments.
- Classes & Interfaces use PascalCase; Methods & Variables use camelCase.
- Constants use UPPER_SNAKE_CASE with static final modifiers.
- Packages use all lowercase reverse domain names (e.g. com.company.module).