如何命名标准化及做好注释？

def calculate_total_price(cart_items):
    """
    计算购物车总价。
    
    参数:
        cart_items (list): 购物车中的商品列表。
        
    返回:
        float: 总价。
    """
    total = sum(item['price'] * item['quantity'] for item in cart_items)
    return total

这段代码使用了描述性强的名字、适当的缩进和清晰的文档字符串，使得任何开发者都能快速理解其功能。

代码布局与格式化

缩进

使用4个空格进行缩进，不要使用制表符（Tab）。这保证了跨平台的一致性。
每一级嵌套增加一个层级的缩进。

行长度

普通代码行的最大长度不应超过79个字符，以便于在标准宽度的编辑器窗口中查看。
对于注释和文档字符串，最大长度为72个字符。

空白行

函数之间或类的方法之间用两个空行分隔，以区分逻辑部分。
类定义前后使用一个空行。

导入声明

导入语句应该放在文件顶部，在模块变量之前。
标准库导入、第三方库导入、本地应用/库的具体顺序进行分组。
每个导入语句单独一行，除非是从同一个包中导入多个模块时可以例外。
避免使用from module import *，因为它会污染当前命名空间并可能引起名称冲突。

字符串引号

单引号（'...'）和双引号（"..."）都可以用于字符串，但应保持一致。如果字符串内包含引号，则可以选择不转义的那个作为外层引号。
多行字符串可以用三重引号（'''...''' 或 """..."""）包围，通常推荐后者用于文档字符串。

PEP 8 – Python编码风格指南

异常处理

Python中的异常处理不仅是捕获错误的手段，更是编写健壮代码的关键。以下是几个最佳实践：

使用具体的异常类型：尽量避免使用裸露的except:，因为它会捕获所有异常，包括系统退出和键盘中断等非预期情况。如果需要捕捉所有程序错误，使用except Exception:。例如：

try:
    result = 10 / 0
except ZeroDivisionError as e:
    print(f"Error: {e}")

最小化try块中的代码：try块内的代码应当尽可能简洁，只包含可能会抛出异常的那一部分。这样做可以减少意外错误被掩盖的风险。例如：

try:
    file = open('example.txt', 'r')
    data = file.read()
except FileNotFoundError as e:
    print(f"File not found: {e}")
finally:
    file.close()

使用上下文管理器：当资源局部于特定代码段时，使用with语句来确保资源能够及时释放。这不仅简化了代码，还提高了安全性。例如：

with open('example.txt', 'r') as file:
    data = file.read()

小贴士：如果你遇到难以调试的异常问题，尝试使用logging模块记录详细的错误信息，而不是简单地打印到控制台。

命名约定

良好的命名约定不仅能提高代码的可读性，还能帮助团队成员快速理解代码意图。以下是几个实用的命名规则：

小写字母加下划线 (snake_case)：适用于函数名、变量名和模块名。例如，calculate_total_price() 或 user_name。
大写常量 (UPPER_CASE_WITH_UNDERSCORES)：对于在整个程序运行期间不变的值，应使用全大写字母，并用下划线分隔单词。如MAX_CONNECTIONS = 100。
帕斯卡命名法 (PascalCase)：用于定义类名。每个单词首字母大写，不使用下划线。比如，CustomerAccount。

案例分析：假设你正在开发一个电子商务平台，下面是一个合理的命名示例：

class ShoppingCart:
    def add_item(self, item_name, quantity):
        # 添加商品到购物车
        pass

def calculate_total_price(cart_items):
    # 计算购物车总价
    pass

注释与文档字符串

注释

注释应当解释“为什么”这样做，而不是“做了什么”，因为后者应该从代码本身就可以看出。
内联注释应该至少有两个空格与代码分开，并且紧跟在代码之后。
不要过度注释，尤其是那些显而易见的地方。

文档字符串

模块、函数、类和方法都应该有文档字符串，遵循reST格式。
文档字符串的第一行应该是简短的摘要，后面跟上详细的说明。
如果文档字符串只有一句话，那么它应该以句号结尾。

函数与变量注解

函数参数和返回值可以添加类型提示，提高代码的可读性和工具的支持。
注解应该遵循一定的格式，例如def function(param: type) -> return_type:。
在定义带有默认值的参数时，如果有类型注解，应在=两边加上空格。

高级话题：类型注解不仅可以用于静态类型检查工具（如mypy），还可以帮助IDE提供更好的代码补全和错误提示。

常见错误及解决方案

为了帮助大家更快上手并避免常见的陷阱，这里列出了一些新手常犯的错误及其改进建议：

不正确的缩进导致的IndentationError：始终使用4个空格进行缩进，不要混用空格和制表符。大多数现代编辑器都支持自动转换制表符为空格的功能。
使用from module import *引起的命名空间污染：尽量避免这种导入方式，因为它会将所有名称直接导入当前命名空间，容易引发冲突。建议显式导入所需的具体名称。
忽略文档字符串的重要性：每个模块、类、方法都应该有一个清晰的文档字符串，说明其功能和参数。这不仅方便自己回顾，也为其他开发者提供了宝贵的参考。