Python非可执行代码注释最佳实践：ML项目多类型注释用法问询

现有做法合理性评估 #

你当前用三类注释区分用途的做法在团队成员均为非专业开发者、代码规模不大的场景下是完全合理的：规则简单直白，不需要额外学习复杂的代码规范，新接触代码的成员看一眼就能快速区分不同注释的作用，符合你降低理解门槛的核心目标。

更稳妥的优化方案（比注释代码块更不容易出错） #

注释掉可执行代码的方式最大的风险是容易出现漏改、多改的问题，比如首次运行时漏了取消某一行的注释，或者后续改了逻辑忘记同步更新注释里的代码。针对你的场景，推荐优先用运行时开关替代注释块，操作更简单，逻辑也更清晰：

def foo():
    """
    does something
    :return: None
    """
    # 首次运行前将下面的变量改为True，运行完改回False即可
    IS_FIRST_RUN = False
    x = Bar()
    if IS_FIRST_RUN:
        x.process()
        x.save_pickle()
    x.load_pickle()

这种方案只需要改一个变量的值，不需要同时操作多行代码的注释状态，对非专业开发者更友好。

注释区分的通用最佳实践 #

如果确实要保留注释可执行代码的写法，你可以沿用当前的三类注释区分规则，只要团队内部统一约定即可，通用的约定规则可以参考：

• 三个双引号包裹的docstring：仅用于说明函数/类的功能、入参含义、返回值含义，是给所有调用这段代码的人看的公共说明
• ## 开头的注释：仅用于写给使用代码的成员看的操作提示、整体逻辑说明，比如操作步骤、开关修改提示
• # 开头的注释：两种用途，要么是临时注释的可执行代码，要么是单行代码的逻辑补充说明，属于逻辑细节的备注

内容的提问来源于stack exchange，提问作者NN314