python编写代码注释建议

注释函数

功能说明：在每个函数的开始部分，用几句话简要描述函数的功能和它所实现的主要操作。

参数说明：对每个参数的类型、作用进行说明。

返回值说明：描述函数返回值的类型及其代表的内容。

示例：

def compute_loss(predictions, targets):
    """
    计算预测和目标之间的均方误差损失。
    
    参数:
        predictions (torch.Tensor): 模型的输出，维度为 (batch_size, num_classes)。
        targets (torch.Tensor): 真实的标签，维度为 (batch_size, num_classes)。
        
    返回:
        torch.Tensor: 损失值，标量。
    """
    loss = torch.mean((predictions - targets) ** 2)
    return loss

注释数据维度和类型

在处理Tensor操作时，注释数据的维度和类型非常关键，尤其是在进行矩阵运算或数据重塑的时候。

示例：

x = torch.randn(100, 3, 32, 32)  # 随机生成数据，维度为 (batch_size, channels, height, width)
y = torch.flatten(x, start_dim=1) # 将图片数据平铺，维度变为 (batch_size, channels*height*width)

注释关键操作步骤

在代码中的关键步骤处加入注释，解释某个操作的原因或其背后的逻辑。

示例：

# 正则化权重，防止过拟合
weights = weights - learning_rate * weights.grad

使用TODO和FIXME标记

TODO：用来标记那些暂时不处理，但将来需要实现或改进的地方。

FIXME：用来标记需要修正的问题，通常是已知的bug或不稳定的代码段。

示例：

# TODO: 添加dropout层以提高模型的泛化能力
# FIXME: 检查维度不匹配的问题

模块和类的文档

对于较大的模块或类，应提供详细的文档注释，说明模块或类的目的和主要功能。

示例：

class ResNet(nn.Module):
    """
    实现ResNet网络结构。
    
    主要特点包括残差块的使用，适用于图像识别任务。
    """
    def __init__(self, num_classes=10):
        super(ResNet, self).__init__()
        self.conv1 = nn.Conv2d(3, 64, kernel_size=7, stride=2, padding=3)
        # 更多初始化代码