python版代码整洁之道

原文：https://github.com/zedr/clean-code-python

python 版的代码整洁之道。目录如下所示：

介绍
变量
函数

1. 介绍

软件工程的原则，来自 Robert C. Martin's 的书--《Clean Code》，而本文则是适用于 Python 版本的 clean code。这并不是一个风格指导，而是指导如何写出可读、可用以及可重构的 pyhton 代码。

并不是这里介绍的每个原则都必须严格遵守，甚至只有很少部分会得到普遍的赞同。下面介绍的都只是指导而已，但这都是来自有多年编程经验的《Clean Code》的作者。

这里的 python 版本是 3.7+

2. 变量

2.1 采用有意义和可解释的变量名

糟糕的写法

ymdstr = datetime.date.today().strftime("%y-%m-%d")

好的写法

current_date: str = datetime.date.today().strftime("%y-%m-%d")

2.2 对相同类型的变量使用相同的词汇

糟糕的写法：这里对有相同下划线的实体采用三个不同的名字

get_user_info()
get_client_data()
get_customer_record()

好的写法：如果实体是相同的，对于使用的函数应该保持一致

get_user_info()
get_user_data()
get_user_record()

更好的写法：python 是一个面向对象的编程语言，所以可以将相同实体的函数都放在类中，作为实例属性或者是方法

class User:
    info : str

    @property
    def data(self) -> dict:
        # ...

    def get_record(self) -> Union[Record, None]:
        # ...

2.3 采用可以搜索的名字

我们通常都是看的代码多于写过的代码，所以让我们写的代码是可读而且可以搜索的是非常重要的，如果不声明一些有意义的变量，会让我们的程序变得难以理解，例子如下所示。

糟糕的写法

# 86400 表示什么呢？
time.sleep(86400)

好的写法

# 声明了一个全局变量
SECONDS_IN_A_DAY = 60 * 60 * 24

time.sleep(SECONDS_IN_A_DAY)

2.4 采用带解释的变量

糟糕的写法

address = 'One Infinite Loop, Cupertino 95014'
city_zip_code_regex = r'^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$'
matches = re.match(city_zip_code_regex, address)

save_city_zip_code(matches[1], matches[2])

还行的写法

这个更好一点，但还是很依赖于正则表达式

address = 'One Infinite Loop, Cupertino 95014'
city_zip_code_regex = r'^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$'
matches = re.match(city_zip_code_regex, address)

city, zip_code = matches.groups()
save_city_zip_code(city, zip_code)

好的写法

通过子模式命名来减少对正则表达式的依赖

address = 'One Infinite Loop, Cupertino 95014'
city_zip_code_regex = r'^[^,\\]+[,\\\s]+(?P.+?)\s*(?P\d{5})?$'
matches = re.match(city_zip_code_regex, address)

save_city_zip_code(matches['city'], matches['zip_code'])

2.5 避免让读者进行猜测

不要让读者需要联想才可以知道变量名的意思，显式比隐式更好。

糟糕的写法

seq = ('Austin', 'New York', 'San Francisco')

for item in seq:
    do_stuff()
    do_some_other_stuff()
    # ...
    # item 是表示什么？
    dispatch(item)

好的写法

locations = ('Austin', 'New York', 'San Francisco')

for location in locations:
    do_stuff()
    do_some_other_stuff()
    # ...
    dispatch(location)

2.6 不需要添加额外的上下文

如果类或者对象名称已经提供一些信息来，不需要在变量中重复。

糟糕的写法

class Car:
    car_make: str
    car_model: str
    car_color: str

好的写法

class Car:
    make: str
    model: str
    color: str

2.7 采用默认参数而不是条件语句

糟糕的写法

def create_micro_brewery(name):
    name = "Hipster Brew Co." if name is None else name
    slug = hashlib.sha1(name.encode()).hexdigest()
    # etc.

这个写法是可以直接给 name 参数设置一个默认数值，而不需要采用一个条件语句来进行判断的。

好的写法

def create_micro_brewery(name: str = "Hipster Brew Co."):
    slug = hashlib.sha1(name.encode()).hexdigest()
    # etc.

3. 函数

3.1 函数参数（2个或者更少）

限制函数的参数个数是很重要的，这有利于测试你编写的函数代码。超过3个以上的函数参数会导致测试组合爆炸的情况，也就是需要考虑很多种不同的测试例子。

没有参数是最理想的情况。一到两个参数也是很好的，三个参数应该尽量避免。如果多于 3 个那么应该需要好好整理函数。通常，如果函数多于2个参数，那代表你的函数可能要实现的东西非常多。此外，很多时候，一个高级对象也是可以用作一个参数使用。

糟糕的写法

def create_menu(title, body, button_text, cancellable):
    # ...

很好的写法

class Menu:
    def __init__(self, config: dict):
        title = config["title"]
        body = config["body"]
        # ...

menu = Menu(
    {
        "title": "My Menu",
        "body": "Something about my menu",
        "button_text": "OK",
        "cancellable": False
    }
)

另一种很好的写法

class MenuConfig:
    """A configuration for the Menu.

    Attributes:
        title: The title of the Menu.
        body: The body of the Menu.
        button_text: The text for the button label.
        cancellable: Can it be cancelled?
    """
    title: str
    body: str
    button_text: str
    cancellable: bool = False


def create_menu(config: MenuConfig):
    title = config.title
    body = config.body
    # ...


config = MenuConfig
config.title = "My delicious menu"
config.body = "A description of the various items on the menu"
config.button_text = "Order now!"
# The instance attribute overrides the default class attribute.
config.cancellable = True

create_menu(config)

优秀的写法

from typing import NamedTuple


class MenuConfig(NamedTuple):
    """A configuration for the Menu.

    Attributes:
        title: The title of the Menu.
        body: The body of the Menu.
        button_text: The text for the button label.
        cancellable: Can it be cancelled?
    """
    title: str
    body: str
    button_text: str
    cancellable: bool = False


def create_menu(config: MenuConfig):
    title, body, button_text, cancellable = config
    # ...


create_menu(
    MenuConfig(
        title="My delicious menu",
        body="A description of the various items on the menu",
        button_text="Order now!"
    )
)

更优秀的写法

rom dataclasses import astuple, dataclass


@dataclass
class MenuConfig:
    """A configuration for the Menu.

    Attributes:
        title: The title of the Menu.
        body: The body of the Menu.
        button_text: The text for the button label.
        cancellable: Can it be cancelled?
    """
    title: str
    body: str
    button_text: str
    cancellable: bool = False

def create_menu(config: MenuConfig):
    title, body, button_text, cancellable = astuple(config)
    # ...


create_menu(
    MenuConfig(
        title="My delicious menu",
        body="A description of the various items on the menu",
        button_text="Order now!"
    )
)

3.2 函数应该只完成一个功能

这是目前为止软件工程里最重要的一个规则。函数如果完成多个功能，就很难对这个函数解耦、测试。如果可以对一个函数分离为仅仅一个动作，那么该函数可以很容易进行重构，并且代码也方便阅读。即便你仅仅遵守这一点建议，你也会比很多开发者更加优秀。

糟糕的写法

def email_clients(clients: List[Client]):
    """Filter active clients and send them an email.
       筛选活跃的客户并发邮件给他们
    """
    for client in clients:
        if client.active:
            email(client)

好的写法

def get_active_clients(clients: List[Client]) -> List[Client]:
    """Filter active clients.
    """
    return [client for client in clients if client.active]


def email_clients(clients: List[Client, ...]) -> None:
    """Send an email to a given list of clients.
    """
    for client in clients:
        email(client)

这里其实是可以使用生成器来改进函数的写法。

更好的写法

def active_clients(clients: List[Client]) -> Generator[Client]:
    """Only active clients.
    """
    return (client for client in clients if client.active)


def email_client(clients: Iterator[Client]) -> None:
    """Send an email to a given list of clients.
    """
    for client in clients:
        email(client)

3.3 函数的命名应该表明函数的功能

糟糕的写法

class Email:
    def handle(self) -> None:
        # Do something...

message = Email()
# What is this supposed to do again?
# 这个函数是需要做什么呢？
message.handle()

好的写法

class Email:
    def send(self) -> None:
        """Send this message.
        """

message = Email()
message.send()

3.4 函数应该只有一层抽象

如果函数包含多于一层的抽象，那通常就是函数实现的功能太多了，应该把函数分解成多个函数来保证可重复使用以及更容易进行测试。

糟糕的写法

def parse_better_js_alternative(code: str) -> None:
    regexes = [
        # ...
    ]

    statements = regexes.split()
    tokens = []
    for regex in regexes:
        for statement in statements:
            # ...

    ast = []
    for token in tokens:
        # Lex.

    for node in ast:
        # Parse.

好的写法

REGEXES = (
   # ...
)


def parse_better_js_alternative(code: str) -> None:
    tokens = tokenize(code)
    syntax_tree = parse(tokens)

    for node in syntax_tree:
        # Parse.


def tokenize(code: str) -> list:
    statements = code.split()
    tokens = []
    for regex in REGEXES:
        for statement in statements:
           # Append the statement to tokens.

    return tokens


def parse(tokens: list) -> list:
    syntax_tree = []
    for token in tokens:
        # Append the parsed token to the syntax tree.

    return syntax_tree

3.5 不要将标志作为函数参数

标志表示函数实现的功能不只是一个，但函数应该仅做一件事情，所以如果需要标志，就将多写一个函数吧。

糟糕的写法

from pathlib import Path

def create_file(name: str, temp: bool) -> None:
    if temp:
        Path('./temp/' + name).touch()
    else:
        Path(name).touch()

好的写法

from pathlib import Path

def create_file(name: str) -> None:
    Path(name).touch()

def create_temp_file(name: str) -> None:
    Path('./temp/' + name).touch()

3.6 避免函数的副作用

函数产生副作用的情况是在它做的事情不只是输入一个数值，返回其他数值这样一件事情。比如说，副作用可能是将数据写入文件，修改全局变量，或者意外的将你所有的钱都写给一个陌生人。

不过，有时候必须在程序中产生副作用--比如，刚刚提到的例子，必须写入数据到文件中。这种情况下，你应该尽量集中和指示产生这些副作用的函数，比如说，保证只有一个函数会产生将数据写到某个特定文件中，而不是多个函数或者类都可以做到。

这条建议的主要意思是避免常见的陷阱，比如分析对象之间的状态的时候没有任何结构，使用可以被任何数据修改的可修改数据类型，或者使用类的实例对象，不集中副作用影响等等。如果你可以做到这条建议，你会比很多开发者都开心。

糟糕的写法

# This is a module-level name.
# It's good practice to define these as immutable values, such as a string.
# However...
name = 'Ryan McDermott'

def split_into_first_and_last_name() -> None:
    # The use of the global keyword here is changing the meaning of the
    # the following line. This function is now mutating the module-level
    # state and introducing a side-effect!
    # 这里采用了全局变量，并且函数的作用就是修改全局变量，其副作用就是修改了全局变量，
    # 第二次调用函数的结果就会和第一次调用不一样了。
    global name
    name = name.split()

split_into_first_and_last_name()

print(name)  # ['Ryan', 'McDermott']

# OK. It worked the first time, but what will happen if we call the
# function again?

好的写法

def split_into_first_and_last_name(name: str) -> list:
    return name.split()

name = 'Ryan McDermott'
new_name = split_into_first_and_last_name(name)

print(name)  # 'Ryan McDermott'
print(new_name)  # ['Ryan', 'McDermott']

另一个好的写法

from dataclasses import dataclass

@dataclass
class Person:
    name: str

    @property
    def name_as_first_and_last(self) -> list:
        return self.name.split() 

# The reason why we create instances of classes is to manage state!
person = Person('Ryan McDermott')
print(person.name)  # 'Ryan McDermott'
print(person.name_as_first_and_last)  # ['Ryan', 'McDermott']

总结

原文的目录实际还有三个部分：

对象和数据结构
类
- 单一职责原则（Single Responsibility Principle, SRP)
- 开放封闭原则（Open/Closed principle，OCP）
- 里氏替换原则（Liskov Substitution Principle ，LSP)
- 接口隔离原则（Interface Segregation Principle ，ISP)
- 依赖倒置原则（Dependency Inversion Principle ，DIP)
不要重复

不过作者目前都还没有更新，所以想了解这部分内容的，建议可以直接阅读《代码整洁之道》对应的这部分内容了。

python版代码整洁之道

1. 介绍

2. 变量

2.1 采用有意义和可解释的变量名

2.2 对相同类型的变量使用相同的词汇

2.3 采用可以搜索的名字

2.4 采用带解释的变量

2.5 避免让读者进行猜测

2.6 不需要添加额外的上下文

2.7 采用默认参数而不是条件语句

3. 函数

3.1 函数参数（2个或者更少）

3.2 函数应该只完成一个功能

3.3 函数的命名应该表明函数的功能

3.4 函数应该只有一层抽象

3.5 不要将标志作为函数参数

3.6 避免函数的副作用

总结

你可能感兴趣的:(python版代码整洁之道)