You could think that comments help with code readability. In reality, the opposite is often the case though.

Proper code formatting (i.e. keeping lines short, adding blank lines etc.) on the other hand helps a lot with reading and understanding code.

Bad Comments

There are plenty of bad comments which you can add to your code. In the best case, "bad" means "redundant" in the worst case, it means "confusing" or even "misleading".

Dividers & Markers

Dividers and markers are redundant. If you code is written in a clean way (i.e. you use proper names etc.), it's obvious what your different code parts are about.

You don't need extra markers for that. They only stop your reading flow and make analyzing the code file harder.

# CLASSES

class User:
    # class definition for User
    pass

class Product:
    # class definition for Product
    pass

# MAIN

user = User()  # create an instance of the User class

Redundant Information

Comments like in this example add nothing. Instead, you stop and spend time reading them - just to learn what you already knew because the code used proper names.

def create_user():
    # function definition for creating a new user
    # add your implementation here
    pass

Comments like in this example add nothing. Instead, you stop and spend time reading them - just to learn what you already knew because the code used proper names.

This command could be useful if you had poor naming:

But of course you should avoid such poor names in the first place.

Commented Out Code

def create_user():
    # function definition for creating a new user
    # add your implementation here
    pass

# Uncomment the following lines if you have a createProduct function
# def create_product():
#     # function definition for creating a new product
#     # add your implementation here
#     pass

We all do that from time to time. But you should try to avoid commenting out code. Instead: Just delete it.

When using source control (e.g. Git), you can always bring back old code if you need it - commented-out code just clutters your code file and makes going through it harder.

Misleading Comments

def login():
    # function definition for user login
    # add your implementation here
    pass