Django Comment

Adding notes and documentation in templates

💬 What are Django Comments?

Django comments allow you to add notes in templates that won't appear in the rendered HTML. Comments help document your code and temporarily disable template sections for debugging purposes. 


<!-- This is an HTML comment -->
{% comment %}
This is a Django comment
{% endcomment %}

Comment Types

📝

Single Line

Quick inline comments 

{# Comment here #}
📄

Multi-line

Block comments for documentation 

{% comment %}
  Multiple lines
{% endcomment %}
🌐

HTML Comment

Standard HTML comments 

<!-- HTML comment -->
🔧

Debug Use

Temporarily disable code 

{# {% if debug %} #}

🔹 Single-Line Comments

Single-line comments use the curly brace hash syntax and are perfect for quick notes. These comments are completely removed from the rendered output and won't appear in the page source. 

<h1>Welcome to My Site</h1>
{# This is a single-line comment #}
<p>This paragraph is visible.</p>

{# TODO: Add user profile section here #}

<div class="content">
    {# Author: John Doe, Date: 2025-01-15 #}
    <p>Main content goes here.</p>
</div>

Output:

Welcome to My Site

This paragraph is visible.

Main content goes here.

🔹 Multi-Line Comments

Multi-line comments use the comment tag block for longer explanations and documentation. Ideal for describing complex template sections or providing detailed implementation notes for other developers. 

{% comment %}
This is a multi-line comment.
You can write multiple lines here.
Useful for longer explanations and documentation.
Author: Jane Smith
Last Modified: 2025-01-15
{% endcomment %}

<div class="user-profile">
    {% comment %}
    User profile section
    - Displays user avatar
    - Shows user name and email
    - Includes edit profile button
    {% endcomment %}
    <h2>User Profile</h2>
    <p>Name: {{ user.name }}</p>
</div>

Output:

User Profile

Name: John Doe

🔹 HTML Comments vs Django Comments

Understanding the difference between HTML and Django comments is crucial. HTML comments appear in page source while Django comments are completely removed during template rendering for better security.

🔸 HTML Comment (Visible in Source) 

<!-- This is an HTML comment -->
<!-- It will appear in the page source code -->
<p>Content here</p>

🔸 Django Comment (Not in Source) 

{# This is a Django comment #}
{# It will NOT appear in the page source #}
<p>Content here</p>

Key Differences:

  • HTML Comments: Visible in browser's "View Source" - use for public notes
  • Django Comments: Completely removed from output - use for internal notes
  • Security: Never put sensitive info in HTML comments
  • Performance: Django comments don't increase page size

🔹 Commenting Out Code

Comments are useful for temporarily disabling template code during development and debugging. Quickly test different implementations without deleting code by commenting out sections you want to disable. 

<h1>My Page</h1>

{% comment %}
Temporarily disabled - testing new design
<div class="old-design">
    <p>Old content here</p>
</div>
{% endcomment %}

<div class="new-design">
    <p>New content here</p>
</div>

{# {% if show_banner %}
    <div class="banner">Special Offer!</div>
{% endif %} #}

Output:

My Page

New content here

🔹 Documentation Comments

Use comments to document your templates for better maintainability. Good documentation helps team members understand template structure, variable requirements, and implementation details quickly. 

{% comment %}
=================================
PRODUCT LISTING TEMPLATE
=================================
Description: Displays all products with filtering
Required Context Variables:
  - products: QuerySet of Product objects
  - categories: List of category names
Author: Development Team
Last Updated: 2025-01-15
=================================
{% endcomment %}

<div class="product-list">
    {# Loop through all products #}
    {% for product in products %}
        <div class="product-card">
            {# Product name and price #}
            <h3>{{ product.name }}</h3>
            <p>${{ product.price }}</p>
        </div>
    {% endfor %}
</div>

🔹 Comment with Optional Note

The comment tag can include an optional note parameter for better organization. This helps categorize comments and makes it easier to search for specific comment types in large templates. 

{% comment "TODO" %}
Add pagination to this section
Implement AJAX loading for better UX
{% endcomment %}

{% comment "FIXME" %}
This section has a bug with mobile display
Need to fix responsive layout
{% endcomment %}

{% comment "NOTE" %}
This template is used by both admin and user views
Be careful when making changes
{% endcomment %}

🔹 Best Practices

💡 Comment Guidelines:

  • Use Django comments for internal notes and sensitive information
  • Use HTML comments only for public-facing documentation
  • Document complex logic to help other developers understand your code
  • Remove debug comments before deploying to production
  • Keep comments updated when you change the code
  • Use TODO/FIXME tags to mark areas needing attention

🔹 Common Use Cases 

{# Navigation menu - updated 2025-01-15 #}
<nav>...</nav>

{% comment %}
Temporarily disabled for A/B testing
Will re-enable after collecting user feedback
{% endcomment %}

{# TODO: Replace with dynamic content from database #}
<p>Static content here</p>

{% comment "SECURITY" %}
This section requires authentication
Ensure user.is_authenticated is checked
{% endcomment %}

{# Debug: Remove before production #}
<p>Debug info: {{ debug_variable }}</p>

🧠 Test Your Knowledge

Which comment type is NOT visible in the browser's page source?