Comments, Keywords and Naming Conventions in Java

Comments

// A single line comment, used for short notes.

/*
   A block comment.
   Useful for a longer explanation.
*/

/**
 * A documentation comment. Tools read these and generate API documentation.
 *
 * @param amount the value to convert, never negative
 * @return the converted value
 */
public double convert(double amount) { ... }

Only the third form is structured. It sits directly above a class, method or field and supports tags such as @param, @return, @throws and @deprecated.

Comments should explain why, not what. A comment restating the code becomes wrong the moment the code changes, and a stale comment is worse than none at all.

Keywords

Keywords are reserved and cannot be used as identifiers. Grouped by purpose they are easier to remember than as an alphabetical list.

true, false and null are literals rather than keywords, but they are equally reserved and cannot name anything.

Contextual keywords

Newer features avoided reserving more words by making them special only in certain positions. var, record, sealed, permits and yield are still legal as variable names, although using them that way is a poor idea.

Identifier rules

• Start with a letter, an underscore or a currency symbol; digits are allowed after the first character.
• No spaces and no operators.
• Case sensitive: total and Total are different identifiers.
• A single underscore on its own is not a valid identifier in modern Java.

Naming conventions

These are conventions rather than compiler rules, but they are followed almost universally, and breaking them makes code look wrong to every Java reader.

Common mistakes

• Starting a class name in lower case, which makes it look like a variable.
• Abbreviating past the point of clarity: calcTotAmt saves nothing worth having.
• Commenting out dead code and leaving it. Delete it; version control remembers.
• Writing a documentation comment that repeats the method name and adds no information.

Best practices

• Name things after the domain, not after their type. customer beats customerObject.
• Document public API with /** ... */ and keep the rest of the code self explanatory.
• Reserve comments for intent, constraints and the reason an unusual choice was made.

Practice

1. Which of these are legal identifiers: 2ndValue, _count, total value, Var, class?
2. Rename public class studentdata and its method public void GetName() to follow convention.
3. Write a documentation comment for a method that withdraws money and throws when the balance is insufficient.

Conclusion

Conventions are how Java code stays readable across teams. Follow them without argument, and spend your judgement on naming things accurately instead.