Python注释非可执行代码的最佳实践

Question

我的ml应用程序有一个很长的预处理阶段，我大部分时间都保持在块注释中。我正在为其他团队成员创建一个应用程序的示例用例，看起来像这样:

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

# x.process()
# x.save_pickle()
x.load_pickle()

请注意，我使用docstring、#和##来区分不同的用法，以提高可读性。

我现在想知道这种方法是否是正确的方法，是否有使用不同注释类型来解释程序功能的最佳实践，而不是代码块注释。

我知道这可能是xy问题，还有其他方法来控制代码块是否运行。请注意，我们都不是专业开发人员，我的目标是使程序逻辑易于其他人阅读和理解。

Answer 1

一般来说，我认为编写需要在第一次运行时注释掉某些内容的代码是不好的做法。但是，如果这是必要的，并且您坚持要朝这个方向走，我会尝试在代码中尽可能多地概述这一点。例如:

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

但是正如我提到的，我宁愿创建一个语句来检查这段代码是否应该运行(检查pickle文件是否存在，如果不存在则执行代码)

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