Python best practises for commenting non executable code

Question

My ML-appplication has a long preprocessing phase that I keep in block comments most of the time. I am creating an example usecase of my application for other team members that looks something like this:

def foo():
    """
    does something
    :return: None
    """
    x = Bar()
    ## uncomment this section during first run
    
    # x.process()
    # x.save_pickle()
    x.load_pickle()

Notice that I am using docstring, # and ## to differentiate between the different usages for better readability.

I am now wondering if this method is the right approach and whether there are best practises for using different comment types for explaining the functionality of the program versus block comments for code.

I know that this could be an XY-problem and there are other ways to control whether or not a block of code is run or not. Note that none of us are professional developers and my goal is to make the program logic easy to read and understand for the others.

Answer 1

Generally, I would consider it bad practice to write code where you need to comment something out on the first run. But if this is needed, and you are adamant about going in this direction, I would try to outline this as much as possible in the code. As an example:

def foo():
    """
    does something
    :return: None
    """
    x = Bar()

    # ---------- uncomment this section during first run ----------
    # x.process()
    # x.save_pickle()
    # -------------------------------------------------------------

    x.load_pickle()

But as I mentioned, I would rather create a statement that checks if this code should be run or not (checking if the pickle file exists and executing the code if it does not)

import os.path

pickle_path = "path/to/pickle/file.pkl"

def foo():
    """
    does something
    :return: None
    """
    x = Bar()

    # ---------- If a pickle file does not exist, run process and save file ----------
    if not os.path.isfile(pickle_path):
        x.process()
        x.save_pickle()

    x.load_pickle()