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

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

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

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

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

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

Python best practises for commenting non executable code

python

comments