代码最佳实践和指南（一）

创建代码是许多数据专业的重要组成部分。但是，创建可以运行的代码只是工作的一半。代码还需要清晰，易于传递，并且对干扰具有鲁棒性。通过在项目中遵循一些编码准则，您可以保存自己以后重新构造代码的时间，并使您的合作者也感到高兴。

在这里，我们探索一些编码最佳实践和指导方针，可以帮助您的代码更清晰，更易于访问。

代码最佳实践：结构和组织

清晰的结构为代码提供了更好的可读性，使其更容易调试和共享。在编写代码时，您可以做几件事来使结构更加清晰和有组织。

选择有意义的变量和函数名

在为变量和函数选择名称时，重要的是要选择相关且有意义的名称。

例如，假设您正在创建一个程序来处理银行帐户信息，并且您需要一个变量来保存帐号。您可能会尝试将此变量称为“number”或“n”。但是，对于第一次查看您的代码的人来说，这些名称并不是非常有用的名称。名称“account_number”提供了更多的信息，并且在后面的代码中更容易理解。

例如，假设你在一段很长的代码中找到了下面的等式。你能说出这个等式是什么吗？

ab=pb+d-w
1

这可能是在代码审查期间遇到的一个具有挑战性的等式。考虑这个替代方案。

account_balance=previous_balance+deposit-withdrawal
1

有了更多信息量的变量名，在一段代码中遵循逻辑就不那么令人沮丧了。同样的概念也适用于函数名。一个名为“name_change”的函数比“change”、“update”或“nc”提供更多的信息。

驼峰命名法和下划线命名

创建变量或函数名有两种普遍接受的约定：驼峰命名和下划线命名。驼峰命名使用大写字母分隔变量名中的单词。下划线命名使用下划线分隔变量中的单词。例如，我们将在驼峰命名中使用变量名“accountNumber”，在下划线命名中使用“account_number”。

使用哪种约定取决于您的个人偏好、公司的编码标准以及您正在使用的编程语言。然而，无论你选择哪种情况，重要的是在整个项目中坚持使用它。在不同的命名约定之间切换看起来很草率，并且可能会造成视觉上的混乱。

有效使用注释和空白

使代码更具可读性的一个简单方法是在整个代码中添加描述性注释。好的注释将确保您的代码可以被其他人解读。你应该添加注释来解释每段代码的作用，特别是任何复杂的方程或函数。您可能还希望向变量定义添加注释，对任何复制的代码给予标记说明，包括对源数据的引用，或者在代码中留下“to do”注释。

当你给自己留下“to do”的时候，考虑一下以“TODO”开始。这种大写将在视觉上脱颖而出，并且很容易搜索，你可以找到你留给自己的所有笔记。

注释是用来使代码更清晰、更易于理解的，而不是用来弥补结构不良的代码。它们应该是清晰、一致，并增强结构良好的代码块。

空白对于可视化地格式化代码也很有用。把空白想象成段落。段落有助于分解大块的文本，这样你就可以快速浏览。类似地，在代码中有策略地添加空白可以更容易地扫描代码以发现错误并跟踪代码的工作。考虑在不同部分或模块之间添加空间。

考虑以下示例：

product_price=materials_cost+manufacturing_cost+shipping_cost
state_tax=product_price*state_tax_rate(state)
federal_tax=product_price*federal_tax_rate
total_tax=state_tax+federal_tax
total_cost=product_price+total_tax
1
2
3
4
5

在第一个例子中，文本被挤压在一起，难以阅读。但是，通过分离内容并使用注释和空格，我们可以使这一部分更具可读性。

#Calculate the price of the product
product_price=materials_cost+manufacturing_cost+shipping_cost
 
#Calculate the tax owed
state_tax=product_price*state_tax_rate(state)
federal_tax=product_price*federal_tax_rate
total_tax=state_tax+federal_tax
 
#Calculate the total cost
total_cost=product_price+total_tax

#TODO create function for looking up state tax rates 
1
2
3
4
5
6
7
8
9
10
11
12

使用缩进和一致的格式

在整个代码中，一致性是关键。在某些语言中，您可以使用缩进来在视觉上分隔不同的部分。例如，这对于区分在循环内部工作的部分很有用。注意：有些语言，比如Python，在功能上使用缩进，所以你可能无法使用它来进行视觉区分。

一致的格式很重要，因为它可以提高可读性并满足读者的期望。

文档和沟通

数据专业中的许多编程任务都是团队努力的结果。即使你花了很长一段时间独自编写代码，这些代码通常会被发送给一个团队进行审查和使用。这使得团队内部关于代码的沟通变得非常重要。

当向团队成员发送代码时，发送有关代码的目的、正确使用以及在运行代码时需要考虑的任何怪癖的信息非常重要。这种类型的通信称为文档，并且应该始终伴随代码。

约定是在一个名为README.txt的文本文件中提供此文档，该文件存储在与主代码文件相同的文件夹中。但是，特定的团队可能有不同的文档标准，例如使用Notion或Google Doc。

应记录哪些内容？

文档文件应该包括接管项目所需的所有信息。应该有关于如何使用代码的信息，代码的目的，体系结构和设计。您应该包括有关代码运行时的输入和输出的注释，以及任何怪癖。

添加有关错误检测和维护的信息也很有用。根据您公司的编码标准，您还可以包括作者信息、项目完成日期或其他信息。

创建读者友好的README文件

在编写README文件时，保持清晰的结构是很重要的。清楚地标记您的输入和输出以及文档的不同部分。将用户最重要的信息放在顶部。任何关键的东西都应该贴上标签，用大写字母、一系列破折号或其他东西突出显示。

文档字符

文档字符串对于第一次使用你的代码的人来说很有用。这是一个写入代码的字符串文字，提供有关代码的信息。在Python中，如果使用命令行查找类、方法或函数的文档，则显示的文本是该代码中的文档字符串。

下面是一个函数的docstring示例：

def calculate_total_price(unit_price, quantity):
    """
    Calculate the total price of items based on unit price and quantity.
 
    Args:
        unit_price (float): The price of a single item.
        quantity (int): The number of items purchased.
 
    Returns:
        float: The total price after multiplying unit price by quantity.
 
    Example:
        >>> calculate_total_price(10.0, 5)
        50.0
    """
    total_price = unit_price * quantity
    return total_price
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

编写代码文档似乎是一项繁重的工作，特别是当您已经知道程序的来龙去脉时。但是，当您将代码传递给其他人或重新访问一段时间没有使用过的旧项目时，适当的文档可以保存大量的时间。