Comments are an essential part of programming since they allow us to document our code, making it easier to be understood by other developers as well as easier to recall by ourselves after a long time away from it. This post will not get into the details of what comments are, if you’re still new to this concept, you can check RealPython’s guide on Writing Comments in Python (Guide). What this post is going to show you is how to comment in Django specifically.
As a matter of fact, Django is a web development framework built on top of the Python programming language, and all its files are Python files (.py extension). This means the same way we comment in Python is exactly how we comment in Django. However, Django also ships with its own templating language, DTL (Django Templating Language), which allows Django logic to be inserted inside HTML files. You can learn more about them from the Templates documentation.
With that being said, the comments in Django’s templates are done differently. So in this post, I’ll also show you how to add comments in Django templates. Along the way, you’ll also learn some cool tricks to automatically comment out code in code editors like VS Code. Hopefully, by the end of this post, you’ll have been equipped with enough knowledge to comment on your Django code. If you’re ready, I’m ready.
Let’s get into it.
Table of Contents
How to add comments in Django
There are two types of comments namely single-line comments and multi-line comments. As both of them explained by their names, the former are comments that take up only one line while the latter spans to at least one of the next lines.
How to Add Django Single-Line Comments
To write a single-line comment in Django, start by typing a hashtag symbol (#) and then the comment next to it. For example, in a .py file:
# This is a Python single-line comment and it will be ignored On the other hand, to write a single-line comment in a Django template, all you have to do is to wrap the text(comment) between a template comment opening tag (opening curly brace followed by a hashtag: {# ) and its closing tag (hashtag followed by closing curly brace: #} ). Here is an example:
{# This is a Django single-line template comment and it will be ignored #}If you’re using Jinja2 as your templating language in a Django project, the syntax for writing comments is the same as the one shown above.
Let’s get into Django multi-line comments.
How to Add Django Multi-Line Comments
To write a multi-line comment in Python, you’d have to use multiline Docstrings because, unlike other programming languages like C++, Java, or C, Python does not have a multiline commenting functionality. Docstrings are actually used to document a function but we can borrow the functionality elsewhere outside of Python functions. To do that, we start by typing 3 consecutive double quotes, then in the next line we write our comment, and then we close it with 3 more consecutive double quotes.
Here is an example:
"""
This is a Python
multi-line Docstring
which can also be used
for commenting
and it still will be ignored
"""By the way, there also are single-line Docstrings which simply are multiline Docstrings that only cover one line. Here is an example:
""" This is a Python single-line Docstring and it will be ignored """To write a multi-line comment in a Django template, you have to wrap the text(comment) between a comment opening tag {% comment %} and a comment closing tag {% endcomment %}.
{% comment %}
<h1> This is a Django multi-line template comment </h1>
<p>and it will be ignored</p>
{% endcomment %}Oh! One more really cool thing about Django multi-line template comments is that you can also add a note in the opening tag. Perhaps you want to document why you commented the code out.
{% comment "The code below, ugh, isn't it getting really annoying?" %}
<h1> This is a Django multi-line template comment </h1>
<p>and it will be ignored</p>
{% endcomment %}One more thing, you cannot put comments inside of comments.
Django multi-line template comments are cool But they seem to take too much time to write relative to each other.
This leads us to our next point: shortcuts to comment out code.
If you want to comment out a snippet of code, first highlight the piece of code, then press the keyboard shortcut Ctrl +/ on Windows or Cmd +/ on Mac. This will work for almost every code editor out there. Be it VS Code or Pycharm.
If you want to uncomment an already commented snippet of code, simply highlight it and press the same keyboard shortcut: CTRL + /.
FAQs: How to Comment in Django?
Does Django templates ignore HTML comments?
Yes, Django ignores HTML comments. You can actually use them as an alternative to Django template comments because the HTML comments do not only comment HTML code but also the Django Template Language (DTL) code.
Here is an example:
<!--The Post How To Comment In Django has {{ post.comment_count }} comment(s).-->You can see that the Django logic between the HTML comment tags is also being commented out. Which is cool.
How to change Django extension comments on vs code
By default, the Django Template Language (DTL) is denoted in VS Code as Django HTML. You can see this on the Status Bar at the bottom of the window in the Editor Language section.
This means that if you use the keyboard shortcut CTRL + / to comment out the code, ( if the language mode is Django HTML), the Django commenting tags will be used. For the HTML comment tags to be used when we press CTRL + /, we have to change the Language mode. To do that follow these steps:
- Click the Editor Language section. (written Django HTML by default)
- A Dialog will pop up at the top for you to select the Language mode that you want. Click HTML on the list of languages displayed.
- Now to put this in practice, highlight a piece of code you want to comment out and press CTRL + /. You’ll see that the code will be commented out using HTML comment tags.
Unfortunately, once you change from Django HTML to HTML alone, Django syntax code will get uncolored. Which may be difficult for you to work on. So always change back to Django HTML once your work is done.
How to comment out a for-loop Django HTML?
This is a rather too specific question. I’ll also answer it more specifically, but the solution can be used for every DTL tag out there. So to comment out a for loop in Django, all you have to do is select the for loop block starting from the {% for %} opening tag up to the {% endfor %} tag of the same block. Then on your keyboard press the shortcut CTRL + /. And you’ll notice that your for-loop block will be wrapped between Django’s comment tags.
{% comment %}
{% for django_comment in comments %}
<h4>{{ django_comment.user }}</h4>
<p>{{ django_comment.detail }}</p>
{% endfor %}
{% endcomment %}An alternative way is to type out the {% comment %} tag before the {% for %} tag, then {% endcomment %} after the {% endfor %} tag.
For other tags, do the same thing.
Conclusion:
This concludes our post. If you found this post helpful, please share it with fellow Django developers whom you think may need to know about adding comments in Django. Otherwise, let me know what you think in the comments section below. I’ll see you in other codingGear guides. Peace!
