JAVA / GETTING STARTED
Comments, identifiers, and naming conventions
Write the three kinds of Java comment, tell a legal identifier from an illegal one, and name classes, methods, variables and constants the way Java expects.
What you will learn
- Pick between //, /* */ and /** */ and know none of them reaches the .class file
- Reject illegal names: keywords, true/false/null, leading digits, hyphens, spaces
- Apply UpperCamelCase, lowerCamelCase and UPPER_SNAKE_CASE to the right declarations
- Read a name's casing to tell a type from a variable from a constant
Understanding Comments, identifiers, and naming conventions
javac reads your source as a stream of tokens, and comments are thrown away during that scan: nothing written in //, /* */ or /** */ survives into the .class file, which is why a comment can never change behaviour. The scanner works strictly left to right, so whichever construct starts first wins. A // inside a string literal is just characters, because the opening quote already put the scanner inside a string token, and a quote inside a comment is likewise just characters. The /** */ form is an ordinary block comment as far as javac is concerned; only the separate javadoc tool cares that it sits immediately before a declaration.
An identifier is any name you invent: classes, methods, variables, parameters, labels. javac enforces four things and nothing more: the first character is a letter, _ or $ (Unicode letters count, so café is a legal name); later characters may also be digits; the name is not a keyword and not true, false or null; and it is spelled identically at every use, because comparison is case sensitive. Length is unlimited and the compiler attaches no meaning to the words themselves, so wheelCount and x7 are equally valid to it. That is precisely why the work of making a name meaningful falls entirely on you.
Java has no sigils marking kinds of names the way $ does in PHP, so casing is the only signal in the source about what a name refers to. The conventions are UpperCamelCase for classes, interfaces, enums and records, lowerCamelCase for methods, variables and parameters, UPPER_SNAKE_CASE for static final constants, and all-lowercase dotted names for packages. They pay off when you read Duration.ofSeconds(timeout): the capital D says a type is being called, the lowercase timeout says a value is being passed, and you looked nothing up to know that. None of it is enforced by javac; it is enforced by whoever reads your code next.
The one naming rule the compiler does check is that a public class lives in a file of the same name, so class OrderTotal must sit in OrderTotal.java.
public class Naming {
/** Every car in this program has the same number of wheels. */
static final int WHEEL_COUNT = 4;
static String describeWheels(int count) {
return count + " wheels";
}
public static void main(String[] args) {
int wheelCount = WHEEL_COUNT; // same words as the constant, a different identifier
int $generated = 1; // legal, but $ is reserved for generated names
int _spare = 2; // legal; a lone _ is not a usable name
System.out.println(describeWheels(wheelCount));
System.out.println($generated + _spare);
System.out.println("Not comments: // and /* */");
/* A block comment can span
several lines, but it does not nest. */
}
}Comments and names mean nothing to the compiler, so their entire job is to let the next human reader see what each name is without looking it up.
Worked examples
Case-different names are different names
Shows that VALUE, value and Value are three unrelated identifiers, and why the convention still matters.
public class CaseMatters {
static final String VALUE = "constant";
public static void main(String[] args) {
String value = "local variable";
String Value = "legal, but looks like a class";
System.out.println(value);
System.out.println(Value);
System.out.println(VALUE);
System.out.println(value.equals(Value));
}
}Example explained
Line 1VALUE, value and Value coexist in one class because the compiler compares names character for character, so none of them collides.
Line 2String Value compiles fine, but the capital letter sends readers hunting for a class named Value, which is the confusion lowerCamelCase avoids.
Line 3value.equals(Value) prints false: two names that differ only in case never share the same storage.
Comments are removed token by token
Demonstrates a block comment deleting tokens mid-expression while // inside a string literal stays as data.
public class CommentsAreNotText {
public static void main(String[] args) {
int a = 2 /* + 40 */ + 1;
System.out.println(a);
System.out.println("2 // 3");
String url = "https://example.com"; // the // in the URL is not a comment
System.out.println(url);
}
}Example explained
Line 12 /* + 40 */ + 1 is scanned as 2 + 1, so a is 3: a block comment can swallow tokens in the middle of an expression.
Line 2In "2 // 3" the scanner is already inside a string token, so // prints as ordinary text.
Line 3On the url line the // after the semicolon does start a real comment, which runs to the end of that line only.
Conventions applied to one small class
Puts each casing rule on the declaration it belongs to: class, constant, method and local variable.
public class OrderTotal {
/** Cents added to every order to cover packaging. */
static final int PACKAGING_FEE_CENTS = 250;
static int totalCents(int itemCents) {
return itemCents + PACKAGING_FEE_CENTS;
}
public static void main(String[] args) {
int itemCents = 1799;
System.out.println(totalCents(itemCents));
System.out.println(PACKAGING_FEE_CENTS);
}
}Example explained
Line 1PACKAGING_FEE_CENTS is static final, so UPPER_SNAKE_CASE warns readers that assigning to it is impossible.
Line 2totalCents is lowerCamelCase and names the value it returns, unit included, so nobody passes dollars into it.
Line 3The Javadoc comment before the field is what the javadoc tool would extract; javac just discards it.
Line 4The class is OrderTotal, so the file must be OrderTotal.java, the single naming rule javac actually enforces.
Important notes
A comment is not a free-text zone. Unicode escapes are decoded before comments are recognised, so // path C:\users\ana fails to compile with 'illegal unicode escape', and a \u000A written in a // comment really does end that comment. Use forward slashes or doubled backslashes in comments.
A lone _ cannot be used as a name you refer to: Java 9 made it a keyword, and from Java 22 a bare _ in certain declarations means an unnamed variable you cannot read back. $ is legal anywhere but is reserved in practice for generated names, which is why nested classes compile to files like Outer$Inner.class.
Common mistakes
Wrapping /* */ around a chunk that already contains a block comment. Comments do not nest, so the inner */ ends the comment early, the lines you meant to disable still compile and run, and the trailing */ raises a syntax error on a line you believed was commented out.
Using a keyword as a name, as in int class = 30; or String new = "x";. javac stops with '<identifier> expected' pointing at the keyword, which says nothing about reserved words; rename to classSize and newName. The literals true, false and null are rejected the same way.
Assuming case is cosmetic: declaring int Total = 0; and later writing total = total + 1; gives 'cannot find symbol', because Total and total are two separate variables rather than two spellings of one.
Try it yourself
Change, predict, then run
In a browser editor, write a class Receipt with static final int TAX_PERCENT = 8; and a method taxOnCents(int cents) returning cents * TAX_PERCENT / 100, with a Javadoc comment above it. Then rename the parameter to Cents, then to class, then to _, and record which of the three javac accepts.
Open the Java workspaceCheck your understanding
Given that javac ignores casing entirely, why does Java convention insist on UpperCamelCase for types and lowerCamelCase for variables?
- javac refuses to compile a class whose name begins with a lowercase letter.
- The JVM inspects the first letter of a name to decide whether to load a class file.
- A bare name could be a variable or a type, and Java resolves the ambiguity in favour of the variable, so casing is the reader's only warning.
- The javadoc tool only documents identifiers that follow the convention.
Show answer
Java prefers a variable when a simple name could mean either, so int String = 5; legally obscures the type String for the rest of that block and the code still compiles; casing is what keeps a reader from mixing the two up. Option 0 is tempting because a public class must match its file name, but the case of the first letter is never checked: public class order {} inside order.java compiles without complaint.