Comments in Code

5.1 How to Write Comments

In Python, just like in many other programming languages, you can write comments in code. Comments help programmers and other project members understand the code, which is especially useful in teamwork and long-term maintenance of programs. In Python, there are several ways to add comments to the code.

Single-line Comments:

These start with the # symbol. Everything following # on the same line is ignored by Python. This type of comment is usually used for brief notes or explanations for a particular line of code. Example:

# This is a single-line comment
print("Hello, World!") # Explanation of the function action

Multi-line Comments:

Python doesn't have a special syntax for multi-line comments, but you can create them using multiple single-line comments or by using triple quotes, though the latter is actually a multi-line string literal that doesn't get 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 string literal that can be used as a comment.
Python interprets it as a string but doesn't do anything with it
unless it's assigned to a variable or used in an expression.
"""
    
      

5.2 Why Write Comments

Using comments in code enhances its readability, makes maintenance and updating easier, and fosters more effective collaboration within teams. Comments should be brief but informative and relevant to serve as useful documentation of the code and not clutter it with unnecessary info.

Docstrings:

These are strings that are typically placed at the beginning of modules, classes, methods, and functions to describe their purpose. They are enclosed in triple double quotes and can be used for automatic documentation generation.

Example:

def add(a, b):
"""
    Function to add two numbers.
    :param a: first addend
    :param b: second addend
    :return: sum of a and b
    """
    return a + b

In the programming world, sometimes developers add comments to their code that not only serve as explanations but also bring a smile. Here are a few examples of funny comments you might come across in code:

Example 1

 

            # I would explain what's going on here, but I don't understand anymore.
        

Example 2

 

    # If this doesn't work, it's someone else's fault.

Example 3

 

    # Came, saw, fixed... and broke.

Example 4

 

    # When I wrote this, only God and I knew how it works.
    # Now only God knows.

These comments can add lightness and humor to the development process, making the codebase less monotonous. They can also serve as reminders that software development is a creative and human process.

5.3 Quickly Comment Code

In PyCharm, you can quickly comment or uncomment code using hotkeys. To do this, select the lines of code you want to change and press Ctrl + / on Windows (or Cmd + / on macOS). This key combination adds or removes the comment symbol on each selected line, making the process quick and efficient.