Return to site

📝🧭 CODE COMMENTS THAT SCALE: HOW TO USE JAVADOC, BLOCK, AND LINE COMMENTS

October 19, 2025

🔸 TL;DR

  1. ▪️ Javadoc → document contracts (what/why, params, returns, exceptions, invariants).
  2. ▪️ Block comments (/* ... */) → provide context (design intent, trade-offs, references).
  3. ▪️ Line comments (//) → clarify weirdness (non-obvious code, edge cases, hacks with reasons).

🔸 WHY THIS MATTERS

  1. ▪️ Comments aren’t decoration—they’re interfaces for humans.
  2. ▪️ Good comments reduce onboarding time, prevent regressions, and make code reviews faster.
  3. ▪️ Choose the right kind of comment for the job to keep noise low and signal high. ✨

🔸 COMMENT TAXONOMY (RECOMMENDED PRACTICE)

▪️ Javadoc = Contract

  • Use on public types/methods (and important internal APIs).
  • Describe purpose, inputs/outputs, pre/postconditions, error cases, thread-safety, performance notes.
  • Keep it stable and testable—if a test can assert it, it belongs here.

▪️ Block Comment = Context

  • Use to explain design decisions: why this algorithm, trade-offs, links to tickets/specs/JEPs.
  • Summarize alternatives considered and why rejected.
  • Great for modules, classes, or complex code paths.

▪️ Line Comment = Weirdness

  • Use sparingly to justify non-obvious code: workarounds, edge-case guards, perf tricks.
  • Be specific: what’s weird + why + source (bug ID, API quirk, platform note).
  • Remove when the code becomes obvious again.

🔸 TINY EXAMPLES

🔸 TEAM CONVENTIONS THAT HELP

  1. ▪️ Write a short “Comment Style Guide” in your repo’s README/CONTRIBUTING.
  2. ▪️ Enforce Javadoc on public APIs via build checks (e.g., Maven/Gradle plugins).
  3. ▪️ In PRs, ask “Contract? Context? Weirdness?” when a comment is added.
  4. ▪️ Prefer links to sources (tickets/benchmarks/specs) over long narratives.


🔸 COMMON PITFALLS TO AVOID

  1. ▪️ Narrating code (“add 1 to i”) — the code already says that.
  2. ▪️ Stale comments—update or delete when behavior changes.
  3. ▪️ Hiding bad design behind comments—fix the code first, then comment what remains non-obvious.
  4. ▪️ Mixing types—don’t put long context in line comments or contracts in block comments.

🔸 TAKEAWAYS

  1. ▪️ Treat comments as API for humans: precise, minimal, and valuable.
  2. ▪️ Match the comment type to the intent (Contract / Context / Weirdness).
  3. ▪️ Keep comments living documents: reviewed, tested, and maintained. ✅

🔸 YOUR TURN

  1. ▪️ Add a Comment Style Guide to your repo today.
  2. ▪️ Pick one module and upgrade comments using this taxonomy.
  3. ▪️ In your next PR, label each new comment with Contract / Context / Weirdness.

Go further with Java certification:

Java👇

Spring👇

PreviousNext
 Return to site
Leave a Comment