python 程式設計規範有哪些？

捷後愚生發表於2023-04-28
Python程式設計

Python 程式設計規範主要包括程式碼佈局、命名規範、註釋規範、函式編寫規範等多個方面，下面給出一些常見的程式設計規範及其示例程式碼。

1. 程式碼佈局規範

程式碼佈局規範主要是指程式碼的縮排、行寬、空行、換行等方面，下面是一些常見的程式碼佈局規範：

  • 使用四個空格作為一個縮排級別，不要使用製表符。
  • 每行程式碼最多不超過 79 個字元，如果需要換行可以使用括號、\ 符號或者三個雙引號。
  • 在函式之間、類之間和邏輯塊之間新增一行空白行，以提高程式碼可讀性。

示例程式碼：

def my_function(arg1, arg2):
    if arg1 == 'value':
        result = arg1 + arg2
    else:
        result = arg2 - arg1
     return result

2. 命名規範

命名規範主要是指變數名、函式名、類名等的命名規則，下面是一些常見的命名規範：

  • 使用全小寫的單詞或下劃線分隔的多個單詞來命名變數或函式。
  • 類名首字母大寫，採用駝峰命名法。
  • 使用字首或字尾來命名私有變數或函式，以單下劃線或雙下劃線開頭或結尾。

示例程式碼：

class MyClass:
    def __init__(self, name):
        self._name = name
     def get_name(self):
        return self._name
     def _helper_method(self):
        pass
my_object = MyClass('John')
print(my_object.get_name())

3. 註釋規範

註釋規範主要是指如何編寫註釋，以方便別人理解你的程式碼，下面是一些常見的註釋規範：

  • 在程式碼中適當新增註釋，以解釋程式碼的目的和實現方法。
  • 給函式和類新增文件字串，以描述其功能和引數等資訊。
  • 避免使用無意義的註釋，例如 “增加變數 x 的值”。

示例程式碼：

# This function calculates the sum of two numbers
def add_numbers(num1, num2):
    """
    Calculate the sum of two numbers.
     Args:
        num1: First number to add.
        num2: Second number to add.
     Returns:
        The sum of the two numbers.
    """
    return num1 + num2

python的文件字串是什麼？

Python 的文件字串是指在模組、類、方法、函式等程式碼段的開頭使用 """ 進行多行字串註釋來描述程式碼段的功能、引數、返回值等資訊的規範化方式。這些文件字串可以被工具程式提取和轉換為 HTML、PDF、Unix 手冊頁等格式的文件，並且可以被程式設計編輯器、互動式幫助工具等程式自動讀取和顯示，對於程式碼的使用與維護十分有幫助。

文件字串應該被寫在程式碼段的開頭，幷包含以下部分：

  • 描述程式碼段的功能和用途。
  • 描述程式碼段的引數名稱、型別、範圍和意義。
  • 描述程式碼段的返回值型別、範圍和意義。
  • 描述程式碼段的異常和錯誤處理資訊。
  • 其他相關的註釋和說明。

下面是一個函式的文件字串示例：

def my_function(arg1, arg2):
    """
    This function adds two numbers.
     Args:
        arg1 (int): The first number.
        arg2 (int): The second number.
     Returns:
        int: The sum of the two numbers.
     Raises:
        ValueError: If either input is not an int.
     Examples:
        >>> my_function(2, 3)
        5
        >>> my_function(2, "three")
        ValueError: arg2 must be an int.
    """
    if not isinstance(arg1, int) or not isinstance(arg2, int):
        raise ValueError("arg1 and arg2 must be ints.")
    return arg1 + arg2

注意，文件字串中的引數型別和異常處理資訊只是規範化的描述，實際程式碼中還需要進行相應的型別判斷和錯誤處理。

4. 函式編寫規範

函式編寫規範主要是指如何編寫函式，以方便別人閱讀和使用你的程式碼，下面是一些常見的函式編寫規範：

  • 函式應該儘可能短小，不要超過 20 行。
  • 函式應該只完成一個明確的任務，而不是多個任務。
  • 函式應該有一個明確的返回值，或者返回 None。

示例程式碼：

def calc_sum(nums):
    """
    Calculate the sum of a list of numbers.
     Args:
        nums: A list of numbers to sum.
     Returns:
        The sum of the list of numbers.
    """
    total = 0
    for num in nums:
        total += num
    return total

相關文章