1. How to write comments
In Python, just like in many other programming languages, you can write comments in the code.
Comments are just text for other programmers:
the Python interpreter doesn't react to them and doesn't execute the code
written in them. Comments help programmers and other team members understand
the code, which is especially useful for collaborative work and long-term
program maintenance. Python has a few ways to add comments to
the code.
Single-line comments:
Begin with the # symbol. Everything after the # on the same line is ignored by the Python interpreter. This type of comment is usually used for short notes or explanations for a specific line of code. Example:
# This is a single-line comment
print("Hello, World!") # Explanation of the function's action
Multi-line comments:
Python doesn't officially have special syntax for multi-line comments, but they can be created using several single-line comments or triple quotes, though the latter is actually a multi-line string literal, not executed as code. Example:
# This is an example of a multi-line comment
# Each line starts with the `#` symbol
or:
"""
This is a multi-line literal that can be used as a comment.
Python interprets it as a string but does nothing with it
if it's not assigned to a variable or used in an expression.
"""
Helpful tip! A literal is a small chunk of
data written directly in the code: a number, a string, and so on.
2. Why write comments
Adding comments to code makes it more readable, easier to maintain and update, and also supports more effective collaboration in teams. Comments should be brief but informative and relevant, so they can serve as helpful documentation for the code without cluttering it with unnecessary information.
Documenting strings (docstrings):
These are multi-line strings typically placed at the beginning of modules, classes, methods, and functions to describe their purpose. They're enclosed in three pairs of double quotes and used for automatically generating documentation.
Example:
def add(a, b):
"""
Function for adding two numbers.
:param a: first number to add
:param b: second number to add
:return: sum of a and b
"""
return a + b
In the programming world, developers sometimes add comments to their code that not only serve as explanations but also bring a smile. Here are some examples of funny comments that you might see in code:
Example 1:
# I would explain what's going on here, but even I don't understand it anymore.
Example 2:
# If this doesn't work, it's someone else's fault.
Example 3:
# Came, saw, fixed...and broke it.
Example 4:
# When I wrote this, only God and I knew how it works.
# Now only God knows.
Example 5:
# Number of hours wasted here = 42.
These comments can add a bit of lightness and humor to the development process, making the codebase less monotonous. They also remind us that software development is a creative and human process.
5.3 Quickly Comment Out Code
In PyCharm IDE, you can quickly comment or uncomment code using hotkeys. To do this, select the lines of code you want to comment or uncomment and press Ctrl + / on Windows (or Cmd + / on macOS). This key combination applies or removes the comment symbol on each selected line, making this process quick and efficient.
GO TO FULL VERSION