ERB Comments: Hide Template Notes from Generated HTML

ERB provides a dedicated comment tag, <%# ... %>, for notes that should be removed when the template is rendered. You will learn how it differs from HTML comments, when to use each kind, and how to keep implementation details out of browser-visible source code.

ERB (Embedded Ruby) templates combine ordinary text, usually HTML, with Ruby instructions. ERB processes its own tags first and produces the final HTML response.

To write an ERB-only comment, use:

<%# This note is for template developers only %>

The ERB renderer discards this tag and its contents. Nothing is added to the final HTML, so visitors cannot see the note by viewing the page source.

This differs from an HTML comment:

<!-- This is an HTML comment -->

An HTML comment is part of the generated response. Browsers do not display it as page content, but it is still delivered to the client and can be inspected in the page source or developer tools.

Use ERB comments for internal implementation notes, temporary template reminders, and explanations of Ruby rendering logic. Do not use HTML comments for secrets, private URLs, credentials, or internal details.

Think of ERB as a kitchen before a meal is served:

• An ERB comment is a note taped inside the kitchen. The chef reads it while preparing the meal, then throws it away. Customers never receive it.
• An HTML comment is a note printed on the menu in invisible ink. It is not obvious during normal use, but anyone who receives the menu can inspect it.

If a note is only for developers working on the template, put it in the kitchen with <%# ... %>.

Use <%# to begin an ERB comment and %> to end it.

<%# Explain why this heading uses a custom CSS class %>
<h1 class="account-title"><%= @user.name %></h1>

Rendered HTML:

<h1 class="account-title">Ava</h1>

The comment is absent.

Multi-line ERB comments

An ERB comment can span multiple lines:

<%#
  This section is shown only to signed-in users.
  Keep the empty-state message consistent with the dashboard.
%>
<section class="dashboard">
  ...
</section>

ERB comment versus HTML comment

<%# Removed before the HTML response is created %>
<!-- Sent to the browser, though not visually displayed -->

Use an ERB comment when the note must not be generated into the HTML.

Consider this template:

<%# Display the current account name %>
<p>Welcome, <%= @account.name %>!</p>

Assume @account.name is "Morgan".

1. ERB reads <%# Display the current account name %>.
2. Because the tag begins with <%#, ERB treats it as a comment and discards it.
3. ERB reads <%= @account.name %>, evaluates the Ruby expression, and inserts Morgan.
4. ERB sends the resulting HTML:

<p>Welcome, Morgan!</p>

No trace of the ERB comment is included in the response.

• Document non-obvious UI decisions: Explain why a template uses a special layout, CSS class, or accessibility attribute.
• Mark future cleanup: Leave a short reminder to replace a temporary view section after a feature rollout.
• Describe required data: Note that a partial expects a local variable such as product or show_price.
• Explain conditional rendering: Clarify why a button is hidden for certain account states.
• Temporarily disable a small template fragment: Comment out a simple line while investigating a layout issue. For larger changes, version control is usually safer and clearer.

Example in a Rails partial:

<%# This partial requires: product and show_price %>
<article class="product-card">
  <h2><%= product.name %></h2>

  <% if show_price %>
    <p><%= number_to_currency(product.price) %></p>
  <% end %>
</article>

In production projects, ERB comments are typically short and explain why, not merely what the code does.

<%# Keep this server-side because pricing depends on the current account's contract. %>
<%= render "pricing", plan: @plan %>

Useful patterns include:

• Partial contracts: Document required locals near the top of a partial.
• Business-rule context: Explain a surprising condition that cannot be understood from the code alone.
• Migration notes: Briefly identify transitional markup that can be removed after a planned change.
• Server-only details: Keep implementation notes out of generated HTML.

Avoid using comments to hide sensitive information or to preserve large blocks of obsolete code. Git history retains removed code, and a ticket or issue tracker is better for substantial follow-up work.

Also avoid placing ERB comments where whitespace is meaningful unless you have verified the rendered output. The comment itself is removed, but surrounding line breaks or spaces in the template may remain.

Using HTML comments when the comment must be private

<!-- Internal: replace this payment provider next month -->

This is sent to the browser. Use an ERB comment instead:

<%# Internal: replace this payment provider next month %>

Forgetting the #

<% This looks like a comment %>

This is interpreted as Ruby code. Since This looks like a comment is not valid Ruby, rendering will fail. Include # immediately after <%:

<%# This is an ERB comment %>

Expecting an ERB comment to appear in View Source

<%# The browser will not receive this %>

That is the intended behavior. If you deliberately need a browser-visible source comment, use an HTML comment, while remembering that it is public.

Putting secrets in any client-side output

Even HTML comments that are visually hidden are not secure. Never place passwords, tokens, private customer data, or sensitive internal instructions in generated HTML.

Commenting out large sections as a long-term strategy

Large commented-out blocks make templates harder to read and can become stale. Delete unused code and rely on version control to recover it if needed.

A useful rule is:

• Use <%# ... %> for comments about the ERB template itself.
• Use <!-- ... --> only when it is acceptable for every browser user to receive the comment.
• Use <% ... %> for Ruby control flow, not for comments.
• Use <%= ... %> when Ruby should produce visible output.

<%# Developer-only ERB comment; removed from output %>

<%#
  Multi-line ERB comment
  Also removed from output
%>

<!-- HTML comment; delivered in the HTML response -->

<% if signed_in? %>       <%# Ruby control-flow tag %>
  <%= current_user.name %> <%# Output-expression tag %>
<% end %>

• Start an ERB comment with <%#.
• End it with %>.
• ERB comments are not sent to the browser.
• HTML comments are sent to the browser and can be inspected.
• Never put sensitive data in HTML comments.
• Prefer brief comments that explain why a decision exists.

How do I comment out code in an ERB file?

Use an ERB comment:

<%# <%= render "old_navigation" %> %>

For a short experiment this is fine. For permanent removal, delete the code and rely on version control.

Are ERB comments visible in browser developer tools?

No. <%# ... %> is removed during ERB rendering, before HTML is sent to the browser.

Are HTML comments hidden from users?

They are not displayed as normal page content, but users can inspect them through View Source or developer tools. Treat them as public.

Can an ERB comment contain Ruby code?

Yes, as text inside the comment, but ERB does not execute it.

<%# @user.admin? %>

Can ERB comments span multiple lines?

Yes. Open with <%#, place the text on one or more lines, and close with %>.

Does <%#= value %> output a value?

No. The # makes the whole ERB tag a comment, so nothing is evaluated or output.

Should I use ERB comments for passwords or API keys?

No. Secrets should not be hard-coded in templates at all. Store them in secure configuration or environment variables.

• ERB output tags — Learn when <%= ... %> inserts Ruby values into HTML.
• ERB control-flow tags — Use <% ... %> for conditions and loops without directly outputting a value.
• Ruby comments — Ruby uses # for source-code comments; ERB comments apply within templates.
• HTML comments — Useful to understand because they look similar but are delivered to the client.
• Rails partials — ERB comments are often used to document a partial's expected local variables.
• HTML escaping in ERB — Important when outputting dynamic values safely with ERB.