-1

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.

3
  • Welcome to Stack Overflow! What is your question? Sep 15, 2021 at 11:38
  • I think there is no "good practice" for it as it's not a good practice at all. If you really need or prefer to work this way then just use what suits you. I think the simplest and better solution here would be to use argparse for handling runtime arguemnts and have something like --first-run handled with if condition.
    – poleszcz
    Sep 15, 2021 at 11:41
  • As mentioned by @poleszcz: there is no "good practice". Often, different teams and companies create their own norms / conventions in order to structure and understand their codebase. However, if this is "new" for you company or team, it is always best to remain as close as possible to the PEP8 standard (which many programmers use as a reference): python.org/dev/peps/pep-0008. Everything that isn't mentioned by PEP8 is a choice on which you and your team will need to agree.
    – TanguyH
    Sep 15, 2021 at 11:48

1 Answer 1

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()

Not the answer you're looking for? Browse other questions tagged or ask your own question.