Chapter 5: Django comment Tag
comment Tag: {% comment %} and its friends — the proper way to write comments inside templates.
Many beginners either:
- use HTML comments <!– –> (which appear in source code — bad for security & debug info)
- or they don’t comment at all and come back 6 months later wondering “what the hell was I thinking here?”
Today I’m going to teach you every realistic way to use Django’s comment tag — like a senior who has written 10,000+ lines of Django templates explaining it to a junior.
We’ll use your polls templates as playground.
1. The Basic {% comment %} … {% endcomment %} Block
This is the official, safe, Django-recommended way to comment out code in templates.
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{% comment %} This section is temporarily disabled while we redesign the homepage hero Planned changes: - Add animated vote counter - Show top 3 trending polls - Use Tailwind classes instead of inline styles TODO: remove this comment after redesign (Feb 2026) {% endcomment %} <!-- The old hero that we don't want in source code --> <div class="old-hero" style="display:none;"> Old welcome message here… </div> |
Why this is better than HTML comment <!– –>
- {% comment %} content never reaches the browser — it’s removed during template rendering
- HTML comments <!– –> are sent to the client → can leak debug info, internal notes, or even sensitive logic
- Django comments can be multi-line and nested (more on nesting later)
2. One-Line Comment (Most Common in Practice)
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 |
{% comment %} TODO: replace with real featured polls query {% endcomment %} <h2>Latest Polls</h2> {% comment %} Temporary fallback message until we have real data {% endcomment %} {% if not latest_questions %} <p>No polls yet — check back soon!</p> {% endif %} |
Pro tip — many teams use short {% comment %} lines right above tricky logic:
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 |
{% comment %} Using forloop.parentloop to show question number in nested choice list {% endcomment %} {% for choice in question.choices.all %} <li> Question {{ forloop.parentloop.counter }} — Choice {{ forloop.counter }}: {{ choice.choice_text }} </li> {% endfor %} |
3. Commenting Out Large Blocks (Debugging / Development)
Very useful when testing:
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{% comment %} Temporarily disabled entire voting form while debugging POST handling Reason: getting CSRF error in console Will re-enable after fixing view {% endcomment %} <form action="{% url 'polls:vote' slug=question.slug %}" method="post"> {% csrf_token %} … </form> |
→ The whole form disappears from output — perfect for isolating bugs
4. Nesting Comments (Allowed & Useful)
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{% comment %} Outer comment explaining big section {% comment %} Inner comment about specific part This was the old way before we switched to F() expression {% endcomment %} Old code that we might need later: {% if choice.votes > 0 %} <span>Already voted</span> {% endif %} {% endcomment %} |
Django fully supports nested {% comment %} blocks — very handy when commenting large legacy code.
5. When NOT to Use {% comment %} (Important!)
Do not use it for:
- Template logic documentation that should be visible to designers/front-end devs → Use regular HTML comments <!– note for designer –> or {# note #} (short form)
Short one-line alternative (less used):
HTML
|
0 1 2 3 4 5 6 |
{# This is a single-line comment — old-style but still works #} |
→ {# … #} is the Jinja-style short comment — works in Django too
6. Real-World Examples from Your Polls App
Put these in index.html or detail.html
Example 1: Comment why we filter is_active
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 12 |
{% comment %} Only show active polls on public list Inactive ones are kept for history / admin review only {% endcomment %} {% for question in latest_questions %} … {% endfor %} |
Example 2: Comment temporary debug code
HTML
|
0 1 2 3 4 5 6 7 8 9 |
{% comment %} Debug: showing raw vote count — remove after styling done {% endcomment %} <div>Raw votes: {{ question.vote_count }}</div> |
Example 3: Comment old layout variant
HTML
|
0 1 2 3 4 5 6 7 8 9 10 11 |
{% comment %} Old card design — keeping for reference until new design approved <div class="old-card">…</div> {% endcomment %} <div class="new-card">… modern design …</div> |
Example 4: Comment TODOs & future plans
HTML
|
0 1 2 3 4 5 6 7 8 9 |
{% comment %} TODO (Feb 2026): Add trending badge if vote_count > 50 in last 24h TODO: Show user avatar next to vote count if logged in {% endcomment %} |
7. Common Beginner Mistakes & Fixes
| Mistake | What happens | Fix / Correct way |
|---|---|---|
| Put comment before {% extends %} | TemplateSyntaxError or blank page | {% extends %} must be first thing in file |
| Use HTML <!– –> for internal notes | Comments visible in source code | Use {% comment %} for anything not meant for browser |
| Forget {% endcomment %} | Syntax error or rest of template ignored | Always close the block |
| Use {# #} for multi-line | Only first line commented | Use {% comment %} … {% endcomment %} for multi-line |
Quick Reference – When to Use Which Comment Style
text
|
0 1 2 3 4 5 6 7 8 |
{% comment %} … {% endcomment %} → Multi-line, internal, safe (never sent to browser) {# short one-liner #} → Quick inline note <!-- HTML comment --> → Visible in source (for designers, SEO notes) |
Your Quick Practice Task (Do This Right Now)
Open polls/templates/polls/index.html or detail.html and add these:
- Above the question loop → {% comment %} Showing only active polls – inactive kept for admin review {% endcomment %}
- Inside loop → {# TODO: add trending badge if votes > 20 #}
- Comment out one <div> temporarily → {% comment %}<div>Old debug</div>{% endcomment %}
- Add {% empty %} message with comment explaining why it exists
Tell me what you want next:
- Which comment style still feels awkward?
- Want to see how to use comments with {% include %} or {% block %}
- Ready to learn other less-used tags ({% verbatim %}, {% spaceless %}, {% widthratio %})?
- Or ready to move to Django Forms + Voting + POST handling?
You’re now using template comments like a pro — small detail, big difference in maintainable code.
Keep going — you’re doing really well! 🚀🇮🇳
