Style Guide cho lập trình Python - Từ A - Z

Bố cục mã

Thụt lề

Sử dụng 4 dấu cách cho mỗi mức thụt lề.

Các dòng tiếp tục phải căn chỉnh các phần tử được bao bọc theo chiều dọc bằng cách sử dụng dòng ngầm định của Python nối bên trong dấu ngoặc đơn, dấu ngoặc nhọn và dấu ngoặc nhọn hoặc sử dụng thụt lề treo. Khi sử dụng thụt lề treo cần lưu ý những điều sau; không được có đối số trên dòng đầu tiên và phải sử dụng thụt lề sâu hơn để phân biệt rõ ràng chính nó là dòng tiếp nối:

# Correct:




# Aligned with opening delimiter.

foo = long_function_name(var_one, var_two,

                         var_three, var_four)




# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.

def long_function_name(

        var_one, var_two, var_three,

        var_four):

    print(var_one)




# Hanging indents should add a level.

foo = long_function_name(

    var_one, var_two,

    var_three, var_four)




# Wrong:




# Arguments on first line forbidden when not using vertical alignment.

foo = long_function_name(var_one, var_two,

    var_three, var_four)




# Further indentation required as indentation is not distinguishable.

def long_function_name(

    var_one, var_two, var_three,

    var_four):

    print(var_one)

Quy tắc 4 dấu cách là tùy chọn cho các dòng tiếp tục.

Không bắt buộc:

# Hanging indents *may* be indented to other than 4 spaces.

foo = long_function_name(

  var_one, var_two,

  var_three, var_four)

Khi phần điều kiện của một câu lệnh ifđủ dài để yêu cầu nó phải được viết trên nhiều dòng, cần lưu ý rằng sự kết hợp của một từ khóa hai ký tự (tức là if), cộng với một khoảng trắng, cùng với một dấu ngoặc đơn mở sẽ tạo ra một 4 tự nhiên. khoảng cách thụt lề cho các dòng tiếp theo của điều kiện nhiều dòng. Điều này có thể tạo ra xung đột trực quan với bộ mã thụt lề được lồng vào bên trong câu lệnh if, cũng sẽ tự nhiên được thụt vào 4 khoảng trắng. PEP này không có quan điểm rõ ràng về cách (hoặc liệu) phân biệt trực quan các dòng có điều kiện như vậy với bộ lồng nhau bên trong if-statement hay không. Các tùy chọn được chấp nhận trong trường hợp này bao gồm, nhưng không giới hạn:

# No extra indentation.

if (this_is_one_thing and

    that_is_another_thing):

    do_something()




# Add a comment, which will provide some distinction in editors

# supporting syntax highlighting.

if (this_is_one_thing and

    that_is_another_thing):

    # Since both conditions are true, we can frobnicate.

    do_something()


# Add some extra indentation on the conditional continuation line.

if (this_is_one_thing

        and that_is_another_thing):

    do_something()

(Cũng xem thảo luận về việc nên ngắt trước hoặc sau toán tử nhị phân bên dưới.)

Dấu ngoặc nhọn / dấu ngoặc nhọn / dấu ngoặc đơn trên các cấu trúc nhiều dòng có thể xếp hàng bên dưới ký tự không có khoảng trắng đầu tiên của dòng cuối cùng của danh sách, như trong:

 my_list = [

    1, 2, 3,

    4, 5, 6,

    ]

result = some_function_that_takes_arguments(
  'a', 'b', 'c',

    'd', 'e', 'f',

    )

hoặc nó có thể được xếp dưới ký tự đầu tiên của dòng bắt đầu cấu trúc nhiều dòng, như trong:

my_list = [

    1, 2, 3,

    4, 5, 6,

]

result = some_function_that_takes_arguments(

    'a', 'b', 'c',

    'd', 'e', 'f',

)

Tab hoặc Dấu cách?

Dấu cách là phương pháp thụt lề ưa thích.

Các tab chỉ nên được sử dụng để duy trì nhất quán với mã đã được thụt lề với các tab.

Python không cho phép trộn các tab và dấu cách để thụt lề.

Độ dài dòng tối đa

Giới hạn tất cả các dòng tối đa là 79 ký tự.

Đối với những khối văn bản dài có ít hạn chế về cấu trúc hơn (docstrings hoặc comment), độ dài dòng phải được giới hạn ở 72 ký tự.

Việc giới hạn chiều rộng cửa sổ trình soạn thảo được yêu cầu giúp có thể có một số tệp mở cạnh nhau và hoạt động tốt khi sử dụng các công cụ xem lại mã trình bày hai phiên bản trong các cột liền kề.

Gói mặc định trong hầu hết các công cụ phá vỡ cấu trúc trực quan của mã, khiến nó khó hiểu hơn. Các giới hạn được chọn để tránh bao bọc trong trình chỉnh sửa với chiều rộng cửa sổ được đặt thành 80, ngay cả khi công cụ đặt một glyph đánh dấu trong cột cuối cùng khi bao quanh các dòng. Một số công cụ dựa trên web có thể không cung cấp gói dòng động.

Một số đội thực sự thích độ dài dòng dài hơn. Đối với mã được duy trì độc quyền hoặc chủ yếu bởi một nhóm có thể đạt được thỏa thuận về vấn đề này, bạn có thể tăng giới hạn độ dài dòng lên đến 99 ký tự, miễn là nhận xét và chuỗi doc vẫn được bao bọc ở 72 ký tự.

Thư viện tiêu chuẩn Python là bảo thủ và yêu cầu giới hạn dòng ở 79 ký tự (và docstrings / comment là 72).

Cách ưu tiên để gói các dòng dài là bằng cách sử dụng sự tiếp nối dòng ngụ ý của Python bên trong dấu ngoặc đơn, dấu ngoặc nhọn và dấu ngoặc nhọn. Các dòng dài có thể được ngắt thành nhiều dòng bằng cách đặt các biểu thức trong ngoặc đơn. Chúng nên được sử dụng thay vì sử dụng dấu gạch chéo ngược để tiếp tục dòng.

Dấu gạch chéo ngược đôi khi vẫn có thể thích hợp. Ví dụ: các câu lệnh dài, nhiều withcâu không thể sử dụng tiếp diễn ngầm định trước Python 3.10, vì vậy dấu gạch chéo ngược được chấp nhận cho trường hợp đó:

with open('/path/to/some/file/you/want/to/read') as file_1, \

     open('/path/to/some/file/being/written', 'w') as file_2:

    file_2.write(file_1.read())

(Xem thảo luận trước về câu lệnh if nhiều dòng để biết thêm suy nghĩ về cách thụt lề của các câu lệnh nhiều dòng như vậy with.)

Một trường hợp khác như vậy là với các assertcâu lệnh.

Đảm bảo thụt lề dòng tiếp tục một cách thích hợp.

Nên ngắt dòng trước hay sau toán tử nhị phân?

Trong nhiều thập kỷ, phong cách được khuyến nghị là ngắt sau các toán tử nhị phân. Nhưng điều này có thể làm ảnh hưởng đến khả năng đọc theo hai cách: các toán tử có xu hướng bị phân tán trên các cột khác nhau trên màn hình và mỗi toán tử được di chuyển ra khỏi toán hạng của nó và lên dòng trước đó. Ở đây, mắt phải làm thêm công việc để phân biệt mục nào được thêm vào và mục nào bị trừ:

# Wrong:

# operators sit far away from their operands

income = (gross_wages +

          taxable_interest +

          (dividends - qualified_dividends) -

          ira_deduction -

          student_loan_interest)

Để giải quyết vấn đề dễ đọc này, các nhà toán học và nhà xuất bản của họ tuân theo quy ước ngược lại. Donald Knuth giải thích quy tắc truyền thống trong loạt bài Máy tính và sắp chữ của mình : “Mặc dù các công thức trong một đoạn văn luôn ngắt sau các phép toán và quan hệ nhị phân, nhưng các công thức được hiển thị luôn ngắt trước các phép toán nhị phân”

Theo truyền thống từ toán học thường dẫn đến mã dễ đọc hơn:

# Correct:

# easy to match operators with operands

income = (gross_wages

          + taxable_interest

          + (dividends - qualified_dividends)

          - ira_deduction

          - student_loan_interest)

Trong mã Python, có thể ngắt trước hoặc sau toán tử nhị phân, miễn là quy ước nhất quán cục bộ. Đối với mã mới, phong cách của Knuth được đề xuất.

Dòng trống

Bao quanh định nghĩa lớp và chức năng cấp cao nhất bằng hai dòng trống.

Các định nghĩa phương thức bên trong một lớp được bao quanh bởi một dòng trống duy nhất.

Các dòng trống bổ sung có thể được sử dụng (một cách tiết kiệm) để phân tách các nhóm chức năng liên quan. Các dòng trống có thể bị bỏ qua giữa một loạt các dòng lót liên quan (ví dụ: một tập hợp các triển khai giả).

Sử dụng các dòng trống trong các hàm, một cách tiết kiệm, để chỉ ra các phần hợp lý.

Python chấp nhận ký tự nguồn cấp dữ liệu biểu mẫu control-L (tức là ^ L) dưới dạng khoảng trắng; Nhiều công cụ coi các ký tự này là dấu phân cách trang, vì vậy bạn có thể sử dụng chúng để tách các trang của các phần liên quan trong tệp của mình. Lưu ý, một số trình chỉnh sửa và trình xem mã dựa trên web có thể không nhận ra control-L là nguồn cấp dữ liệu biểu mẫu và sẽ hiển thị một glyph khác ở vị trí của nó.

Mã hóa tệp nguồn

Mã trong bản phân phối Python cốt lõi phải luôn sử dụng UTF-8 và không được có khai báo mã hóa.

Trong thư viện chuẩn, các mã hóa không phải UTF-8 chỉ nên được sử dụng cho mục đích thử nghiệm. Sử dụng các ký tự không phải ASCII một cách tiết kiệm, tốt nhất là chỉ để biểu thị địa điểm và tên người. Nếu sử dụng các ký tự không phải ASCII làm dữ liệu, hãy tránh các ký tự Unicode ồn ào như z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ và các dấu thứ tự byte.

Tất cả các số nhận dạng trong thư viện chuẩn Python PHẢI sử dụng các số nhận dạng chỉ ASCII và NÊN sử dụng các từ tiếng Anh nếu có thể (trong nhiều trường hợp, các từ viết tắt và thuật ngữ kỹ thuật được sử dụng không phải là tiếng Anh).

Các dự án nguồn mở với đối tượng toàn cầu được khuyến khích áp dụng chính sách tương tự.

>>> Đăng ký và tham khảo thông tin về  Khóa học Python của T3H ngay hôm nay!