Python函数缺失文档字符串（missing-function-docstring）问题解决及规范咨询

一、提示出现的原因 #

Pylance的missing-function-docstring提示是在提醒你：当前函数缺少文档字符串（docstring）。这是PEP 8（Python官方代码风格指南）的要求之一，目的是让代码更易读、便于协作和后期维护。

二、处理提示的方法 #

1. 添加规范的文档字符串（推荐） #

给函数添加清晰的docstring，说明函数功能、参数、返回值等信息。以下用Google风格的docstring修改你的代码：

def retangulo(larg, comp):
    """计算并打印矩形场地的面积。

    Args:
        larg (int | float): 矩形场地的宽度
        comp (int | float): 矩形场地的长度

    Returns:
        None: 函数仅输出计算结果，无返回值
    """
    area = larg * comp
    print(f'A área de um terreno {larg} x {comp} é {area}.')

添加后Pylance的提示会自动消失，其他开发者也能快速理解函数的用途。

2. 临时禁用提示（不推荐） #

如果是非常简单的一次性函数，不想添加docstring，可以通过注释单独禁用该函数的检查：

# pylance: disable=missing-function-docstring
def retangulo(larg, comp):
    area = larg * comp
    print(f'A área de um terreno {larg} x {comp} é {area}.')

注意：不建议全局关闭该检查，docstring对代码维护至关重要。

三、Python代码规范核心要点（基于PEP 8） #

• 文档字符串：所有公共模块、函数、类、方法必须添加docstring，明确说明功能、参数、返回值、异常等信息。
• 命名规则：
  • 函数、变量名用蛇形命名法（小写+下划线），比如calculate_rectangle_area
  • 类名用大驼峰命名法（每个单词首字母大写），比如RectangleAreaCalculator
• 缩进：统一使用4个空格缩进，禁止混用制表符和空格
• 行长度：每行代码尽量不超过79字符，注释不超过72字符
• 空格规范：运算符两侧、逗号后必须加空格，比如a + b而非a+b，func(x, y)而非func(x,y)
• 注释：注释要简洁有用，避免冗余（不用注释解释显而易见的代码），仅在复杂逻辑处添加说明

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