Platform under construction

JavaScript Basics

Basic

Comments

Comments are notes for humans. They explain intent, warnings and context, but they should not repeat obvious code or hide dead code forever.

// Keep this delay aligned with the CSS transition.
const animationDuration = 220;

setTimeout(closePanel, animationDuration);

JavaScript Basics

Good comments explain why, not what the code already says.

JavaScript has single-line comments with // and block comments with /* ... */. Both are ignored when the code runs.

A useful comment gives context that the code cannot show by itself: a business rule, browser workaround, security reason or a warning about timing.

Bad comments are noise. If the code says total = price * count, a comment that says calculate total adds nothing. Clear code first, comments second.

// single-line

Best for short notes above or beside one line of code.

/* block */

Useful for longer notes, temporary section labels or documentation blocks.

JSDoc style

Structured comments can document functions, parameters and return values.

No secrets

Comments are shipped with source in many projects. Do not put passwords or private keys in comments.

Examples

Good JavaScript is clear, scoped and easy to debug.

Comment gives missing context

// The API returns cents. Convert once at the boundary so UI code works with display credits.
const amountInEuros = response.amountInCents / 100;

// Keep focus inside the modal while it is open.
trapFocus(modal);

Comments repeat obvious code

// Set the display label
const name = "User A";

// Add one
count = count + 1;

// old code maybe needed later
// submitBrokenFormForever();

Rules that matter

Learn the decision before memorizing the keyword.

JavaScript becomes much easier when you understand why a pattern exists. The syntax is only the surface; the real skill is choosing the right behavior for the interface.

Explain intent

Use comments for why a decision exists, not for what the syntax already says.

Keep comments close

Put the note near the code it explains.

Update comments with code

Wrong comments are worse than no comments because they mislead the next developer.

Remove dead code

Use version control instead of leaving old code commented out forever.

Never store secrets

Comments can leak in repositories, source maps, backups or shared snippets.

Prefer clear names first

If a better variable name removes the need for a comment, rename the variable.

Production thinking

JavaScript quality is visible in behavior, reliability and trust.

Why does this matter?

Comments are part of maintainability. They help future developers understand decisions that are not visible from syntax alone.

Accessibility

Comments are useful around focus management, ARIA updates and keyboard behavior because those decisions are easy to break accidentally.

Production note

Production teams should treat comments as documentation that must stay accurate. Outdated comments slow down debugging.

SEO note

Comments do not help ranking. They help developers avoid breaking the JavaScript that supports navigation, content and interaction.

Live code lab

Change the HTML, CSS or JavaScript and run the result.

The preview runs inside an isolated iframe. The JavaScript is placed inside the HTML editor for now, so every example stays together and remains easy to understand.

Mini assignment

Try this now.

Add one useful comment above the event listener.
Remove a comment if the variable name already explains enough.
Change transitionDuration and update the comment if needed.

Practice assignment

Do this before moving to the next topic.

Write one single-line comment that explains a business rule.
Write one block comment for a larger warning.
Find one obvious comment and replace it with a clearer variable name.

HTML + JavaScript CSS

Live preview

Self-check

Before you continue, prove that you understand Comments.