Tham số đặt python
Tài liệu này đưa ra các quy ước viết mã cho mã Python bao gồm thư viện chuẩn trong bản phân phối Python chính. Vui lòng xem PEP thông tin đi kèm mô tả các nguyên tắc về kiểu dáng cho mã C trong triển khai C của Python Show Tài liệu này và PEP 257 (Quy ước về chuỗi tài liệu) được điều chỉnh từ bài tiểu luận Hướng dẫn về Phong cách Python ban đầu của Guido, với một số bổ sung từ hướng dẫn về phong cách của Barry Hướng dẫn về phong cách này phát triển theo thời gian khi các quy ước bổ sung được xác định và các quy ước trước đây trở nên lỗi thời bởi những thay đổi trong chính ngôn ngữ đó Nhiều dự án có hướng dẫn về phong cách mã hóa của riêng họ. Trong trường hợp có bất kỳ xung đột nào, các hướng dẫn dành riêng cho dự án đó sẽ được ưu tiên cho dự án đó Một trong những hiểu biết quan trọng của Guido là mã được đọc thường xuyên hơn nhiều so với mã được viết. Các nguyên tắc được cung cấp ở đây nhằm cải thiện khả năng đọc mã và làm cho mã nhất quán trên nhiều loại mã Python. Như PEP 20 nói, "Khả năng đọc được tính" Hướng dẫn về phong cách là về tính nhất quán. Tính nhất quán với hướng dẫn phong cách này là rất quan trọng. Tính nhất quán trong một dự án quan trọng hơn. Tính nhất quán trong một mô-đun hoặc chức năng là quan trọng nhất Tuy nhiên, hãy biết khi nào không nhất quán - đôi khi các đề xuất hướng dẫn về phong cách không áp dụng được. Khi nghi ngờ, hãy sử dụng phán đoán tốt nhất của bạn. Nhìn vào các ví dụ khác và quyết định những gì có vẻ tốt nhất. Và đừng ngần ngại hỏi Đặc biệt. không phá vỡ khả năng tương thích ngược chỉ để tuân thủ PEP này Một số lý do chính đáng khác để bỏ qua một hướng dẫn cụ thể
Sử dụng 4 dấu cách cho mỗi mức thụt đầu dòng 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 ẩn của Python nối bên trong dấu ngoặc đơn, dấu ngoặc 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 xem xét những điều sau đây; # 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 theo 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 câu lệnh # Wrong: # operators sit far away from their operands income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)7 đủ dài để yêu cầu nó được viết trên nhiều dòng, điều đáng chú ý là sự kết hợp của từ khóa hai ký tự (i. e. # Wrong: # operators sit far away from their operands income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)7), cộng với một khoảng trắng, cộng với dấu ngoặc đơn mở sẽ tạo ra một khoảng thụt lề 4 dấu cách tự nhiên cho các dòng tiếp theo của câu đ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 bên trong câu lệnh # Wrong: # operators sit far away from their operands income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)7, vốn dĩ cũng sẽ đượ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 thức (hoặc liệu) có phân biệt trực quan hơn nữa các dòng điều kiện như vậy với bộ lồng nhau bên trong câu lệnh # Wrong: # operators sit far away from their operands income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)7 hay không. Các tùy chọn có thể chấp nhận được trong tình huống 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 phần thảo luận về việc ngắt trước hay sau toán tử nhị phân bên dưới. ) Dấu ngoặc nhọn/dấu ngoặc vuông/dấu ngoặc đơn trên các cấu trúc nhiều dòng có thể xếp hàng dưới ký tự không phải khoảng trắng đầu tiên của dòng cuối cùng của danh sách, như trong ________số 8 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', ) Khoảng trắng là phương pháp thụt đầu dòng ưa thích Các tab chỉ nên được sử dụng để duy trì tính nhất quán với mã đã được thụt lề bằng các tab Python không cho phép trộn các tab và dấu cách để thụt đầu dòng Giới hạn tất cả các dòng tối đa 79 ký tự Đối với các khối văn bản dài có ít hạn chế về cấu trúc hơn (chuỗi tài liệu hoặc nhận xét), độ dài dòng nên được giới hạn ở 72 ký tự Việc giới hạn độ rộng cửa sổ trình chỉnh sửa được yêu cầu giúp có thể mở nhiều tệp cạnh nhau và hoạt động tốt khi sử dụng các công cụ xem xét mã hiển thị 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ó trở nên khó hiểu hơn. Các giới hạn được chọn để tránh ngắt dòng trong trình chỉnh sửa có chiều rộng cửa sổ được đặt thành 80, ngay cả khi công cụ đặt một hình tượng đánh dấu trong cột cuối cùng khi ngắt dòng. Một số công cụ dựa trên web có thể hoàn toàn không cung cấp tính năng ngắt dòng động Một số đội thực sự thích chiều 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 tới 99 ký tự, miễn là các nhận xét và chuỗi tài liệu vẫn được gói gọn trong 72 ký tự Thư viện chuẩn Python là bảo thủ và yêu cầu giới hạn dòng ở 79 ký tự (và tài liệu/nhận xét đến 72) Cách ưu tiên để gói các dòng dài là sử dụng phần tiếp theo dòng ngụ ý của Python bên trong dấu ngoặc đơn, dấu ngoặc và dấu ngoặc nhọn. Các dòng dài có thể được chia thành nhiều dòng bằng cách gói 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 Đôi khi, dấu gạch chéo ngược vẫn có thể phù hợp. Ví dụ: câu lệnh # 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)01 dài, nhiều câu lệnh không thể sử dụng tiếp tục ẩn 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 đó # 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)1 (Xem phần thảo luận trước để biết thêm suy nghĩ về cách thụt đầu dòng của các câu lệnh # 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)01 nhiều dòng như vậy. ) Một trường hợp khác như vậy là với câu lệnh # 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)03 Đảm bảo thụt lề dòng tiếp theo một cách thích hợp Trong nhiều thập kỷ, phong cách được đề xuất là phá vỡ sau các toán tử nhị phân. Nhưng điều này có thể ảnh hưởng đến khả năng đọc theo hai cách. các toán tử có xu hướng nằm rải rác 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 việc nhiều hơn để biết mục nào được thêm 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 sê-ri 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 # 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)0 Trong mã Python, được phép 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 Bao quanh các định nghĩa lớp và chức năng cấp cao nhất với 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 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ể được bỏ qua giữa một loạt các dòng đơn có liên quan (e. g. một tập hợp các triển khai giả) Sử dụng ít dòng trống trong các hàm để biểu thị các phần logic Python chấp nhận điều khiển-L (i. e. ^L) biểu mẫu ký tự nguồn cấp dữ liệu dưới dạng khoảng trắng; . 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 dưới dạng nguồn cấp dữ liệu biểu mẫu và sẽ hiển thị một ký tự khác ở vị trí của 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, 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 ít ký tự không phải ASCII, 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à dấu thứ tự byte Tất cả các mã định danh trong thư viện chuẩn Python PHẢI sử dụng các mã định danh chỉ ASCII và NÊN sử dụng các từ tiếng Anh bất cứ khi nào khả thi (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ự
Cấp độ mô-đun “dunders” (i. e. tên có hai dấu gạch dưới ở đầu và hai ở cuối) chẳng hạn như ________ 106, ________ 107, ______ 108, v.v. nên được đặt sau chuỗi tài liệu mô-đun nhưng trước bất kỳ câu lệnh nhập nào ngoại trừ nhập khẩu # 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)09. Python yêu cầu các lần nhập trong tương lai phải xuất hiện trong mô-đun trước bất kỳ mã nào khác ngoại trừ chuỗi tài liệu # 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)6 Trong Python, chuỗi trích dẫn đơn và chuỗi trích dẫn kép giống nhau. PEP này không đưa ra khuyến nghị cho việc này. Chọn một quy tắc và tuân theo nó. Tuy nhiên, khi một chuỗi chứa các ký tự trích dẫn đơn hoặc kép, hãy sử dụng ký tự còn lại để tránh dấu gạch chéo ngược trong chuỗi. Nó cải thiện khả năng đọc Đối với chuỗi trích dẫn ba lần, luôn sử dụng ký tự trích dẫn kép để phù hợp với quy ước chuỗi tài liệu trong PEP 257 Tránh khoảng trắng không liên quan trong các trường hợp sau
Dấu phẩy ở cuối thường là tùy chọn, ngoại trừ chúng là bắt buộc khi tạo một bộ gồm một phần tử. Để rõ ràng, nên đặt phần sau trong dấu ngoặc đơn (dư thừa về mặt kỹ thuật) my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )3 my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )4 Khi dấu phẩy ở cuối là dư thừa, chúng thường hữu ích khi hệ thống kiểm soát phiên bản được sử dụng, khi danh sách giá trị, đối số hoặc mục đã nhập dự kiến sẽ được mở rộng theo thời gian. Mẫu là đặt từng giá trị (v.v. ) trên một dòng, luôn thêm dấu phẩy ở cuối và thêm dấu ngoặc đơn/dấu ngoặc nhọn/dấu ngoặc nhọn trên dòng tiếp theo. Tuy nhiên, sẽ không có ý nghĩa gì khi có dấu phẩy ở cuối trên cùng một dòng với dấu phân cách đóng (ngoại trừ trường hợp trên của các bộ dữ liệu đơn lẻ) my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )5 my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )6 Bình luận mâu thuẫn với mã còn tệ hơn là không có bình luận. Luôn ưu tiên cập nhật các nhận xét khi mã thay đổi Nhận xét phải là câu hoàn chỉnh. Từ đầu tiên phải được viết hoa, trừ khi đó là từ định danh bắt đầu bằng chữ cái viết thường (không bao giờ thay đổi trường hợp định danh. ) Bình luận khối thường bao gồm một hoặc nhiều đoạn văn được xây dựng từ các câu hoàn chỉnh, với mỗi câu kết thúc bằng một dấu chấm Bạn nên sử dụng hai khoảng trắng sau khoảng thời gian kết thúc câu trong các nhận xét nhiều câu, ngoại trừ sau câu cuối cùng Đảm bảo rằng nhận xét của bạn rõ ràng và dễ hiểu đối với những người nói ngôn ngữ khác mà bạn đang viết Lập trình viên Python từ các quốc gia không nói tiếng Anh. vui lòng viết nhận xét của bạn bằng tiếng Anh, trừ khi bạn chắc chắn 120% rằng mã sẽ không bao giờ được đọc bởi những người không nói ngôn ngữ của bạn Chặn nhận xét thường áp dụng cho một số (hoặc tất cả) mã theo sau chúng và được thụt vào cùng cấp độ với mã đó. Mỗi dòng của một bình luận khối bắt đầu bằng một # 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)10 và một khoảng trắng (trừ khi đó là văn bản thụt vào bên trong bình luận) Các đoạn bên trong một chú thích khối được phân tách bằng một dòng chứa một # 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)10 Sử dụng bình luận nội tuyến một cách tiết kiệm Một bình luận nội tuyến là một bình luận trên cùng một dòng với một tuyên bố. Nhận xét nội tuyến phải được phân tách bằng ít nhất hai dấu cách từ câu lệnh. Họ nên bắt đầu bằng một dấu # và một dấu cách Nhận xét nội tuyến là không cần thiết và trên thực tế gây mất tập trung nếu chúng nêu rõ ràng. Đừng làm điều này my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )7 Nhưng đôi khi, điều này là hữu ích my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )8 Các quy ước để viết các chuỗi tài liệu tốt (a. k. a. “docstrings”) bất tử trong PEP 257
Các quy ước đặt tên của thư viện Python hơi lộn xộn, vì vậy chúng tôi sẽ không bao giờ hiểu được điều này hoàn toàn nhất quán – tuy nhiên, đây là các tiêu chuẩn đặt tên hiện được khuyến nghị. Các mô-đun và gói mới (bao gồm cả khung của bên thứ ba) nên được viết theo các tiêu chuẩn này, nhưng khi một thư viện hiện có có kiểu khác, thì nên ưu tiên tính nhất quán nội bộ Các tên hiển thị cho người dùng dưới dạng các phần công khai của API phải tuân theo các quy ước phản ánh cách sử dụng thay vì triển khai Có rất nhiều cách đặt tên khác nhau. Nó giúp có thể nhận ra phong cách đặt tên nào đang được sử dụng, độc lập với những gì chúng được sử dụng cho Các kiểu đặt tên sau đây thường được phân biệt
Ngoài ra còn có kiểu sử dụng tiền tố ngắn duy nhất để nhóm các tên có liên quan lại với nhau. Điều này không được sử dụng nhiều trong Python, nhưng nó được đề cập cho đầy đủ. Ví dụ: hàm # 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)24 trả về một bộ có các mục theo truyền thống có tên như # 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)25, # 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)26, # 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)27, v.v. (Điều này được thực hiện để nhấn mạnh sự tương ứng với các trường của cấu trúc lệnh gọi hệ thống POSIX, giúp lập trình viên quen với điều đó. ) Thư viện X11 sử dụng chữ X đứng đầu cho tất cả các chức năng công khai của nó. Trong Python, kiểu này thường được coi là không cần thiết vì tên thuộc tính và phương thức được thêm tiền tố vào đối tượng và tên hàm được thêm tiền tố vào tên mô-đun Ngoài ra, các biểu mẫu đặc biệt sau sử dụng dấu gạch dưới ở đầu hoặc ở cuối được công nhận (những biểu mẫu này thường có thể được kết hợp với bất kỳ quy ước trường hợp nào)
Không bao giờ sử dụng các ký tự 'l' (chữ el viết thường), 'O' (chữ oh viết hoa) hoặc 'I' (chữ viết hoa eye) làm tên biến ký tự đơn Trong một số phông chữ, các ký tự này không thể phân biệt được với các chữ số một và số không. Khi muốn sử dụng 'l', hãy sử dụng 'L' để thay thế Mã định danh được sử dụng trong thư viện tiêu chuẩn phải tương thích với ASCII như được mô tả trong PEP 3131 Các mô-đun nên có tên ngắn, toàn chữ thường. Dấu gạch dưới có thể được sử dụng trong tên mô-đun nếu nó cải thiện khả năng đọc. Các gói Python cũng phải có tên ngắn, viết thường, mặc dù việc sử dụng dấu gạch dưới không được khuyến khích Khi một mô-đun mở rộng được viết bằng C hoặc C++ có một mô-đun Python đi kèm cung cấp cấp độ cao hơn (e. g. hướng đối tượng hơn), mô-đun C/C++ có dấu gạch dưới ở đầu (e. g. # 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)38) Tên lớp thường nên sử dụng quy ước CapWords Quy ước đặt tên cho các chức năng có thể được sử dụng thay thế trong trường hợp giao diện được ghi lại và được sử dụng chủ yếu dưới dạng có thể gọi được Lưu ý rằng có một quy ước riêng cho tên dựng sẵn. hầu hết các tên dựng sẵn là các từ đơn (hoặc hai từ chạy cùng nhau), với quy ước CapWords chỉ được sử dụng cho các tên ngoại lệ và hằng số dựng sẵn Tên của các biến loại được giới thiệu trong PEP 484 thường nên sử dụng CapWords ưu tiên tên ngắn. # 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)39, # 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)40, # 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)41. Nên thêm các hậu tố # 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)42 hoặc # 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)43 vào các biến được sử dụng để khai báo hành vi hiệp biến hoặc trái ngược tương ứng my_list = [ 1, 2, 3, 4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )2 Vì các ngoại lệ phải là các lớp, quy ước đặt tên lớp được áp dụng ở đây. Tuy nhiên, bạn nên sử dụng hậu tố "Lỗi" trên tên ngoại lệ của mình (nếu ngoại lệ thực sự là lỗi) (Hãy hy vọng rằng các biến này chỉ được sử dụng bên trong một mô-đun. ) Các quy ước gần giống như các quy ước cho hàm Các mô-đun được thiết kế để sử dụng qua # 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)29 nên sử dụng cơ chế # 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)06 để ngăn việc xuất các toàn cầu hoặc sử dụng quy ước cũ hơn về việc thêm tiền tố vào các toàn cầu đó bằng dấu gạch dưới (bạn có thể muốn thực hiện điều này để chỉ ra các toàn cầu này là “mô-đun không công khai”) Tên chức năng phải là chữ thường, với các từ được phân tách bằng dấu gạch dưới khi cần thiết để cải thiện khả năng đọc Tên biến tuân theo quy ước giống như tên hàm mixCase chỉ được phép trong các ngữ cảnh mà đó đã là phong cách phổ biến (e. g. luồng. py), để duy trì khả năng tương thích ngược Luôn sử dụng # 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)46 cho đối số đầu tiên của các phương thức thể hiện Luôn sử dụng # 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)47 cho đối số đầu tiên của các phương thức lớp Nếu tên của một đối số hàm xung đột với một từ khóa dành riêng, thì tốt hơn hết là nối thêm một dấu gạch dưới ở cuối thay vì sử dụng từ viết tắt hoặc viết sai chính tả. Do đó, # 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)48 tốt hơn # 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)49. (Có lẽ tốt hơn là tránh đụng độ như vậy bằng cách sử dụng từ đồng nghĩa. ) Sử dụng quy tắc đặt tên hàm. chữ thường với các từ được phân tách bằng dấu gạch dưới khi cần thiết để cải thiện khả năng đọc Chỉ sử dụng một dấu gạch dưới hàng đầu cho các phương thức không công khai và các biến thể hiện Để tránh đụng độ tên với các lớp con, hãy sử dụng hai dấu gạch dưới ở đầu để gọi quy tắc xáo trộn tên của Python Python xáo trộn những tên này với tên lớp. nếu lớp Foo có một thuộc tính có tên là # 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)50, nó không thể được truy cập bởi # 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)51. (Người dùng khăng khăng vẫn có thể truy cập bằng cách gọi # 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)52. ) Nói chung, chỉ nên sử dụng hai dấu gạch dưới ở đầu để tránh xung đột tên với các thuộc tính trong các lớp được thiết kế để phân lớp Ghi chú. có một số tranh cãi về việc sử dụng __names (xem bên dưới) Các hằng số thường được xác định ở cấp độ mô-đun và được viết bằng tất cả các chữ in hoa với dấu gạch dưới ngăn cách các từ. Ví dụ bao gồm # 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)53 và # 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)54 Luôn quyết định xem các phương thức và biến thể hiện của một lớp (gọi chung là. “thuộc tính”) phải ở chế độ công khai hoặc không công khai. Nếu nghi ngờ, hãy chọn không công khai; Các thuộc tính công khai là những thuộc tính mà bạn muốn các máy khách không liên quan trong lớp của mình sử dụng, với cam kết của bạn để tránh các thay đổi không tương thích ngược. Các thuộc tính không công khai là những thuộc tính không dành cho bên thứ ba sử dụng; Chúng tôi không sử dụng thuật ngữ “riêng tư” ở đây, vì không có thuộc tính nào thực sự riêng tư trong Python (không có số lượng công việc không cần thiết nói chung) Một loại thuộc tính khác là những thuộc tính nằm trong “API lớp con” (thường được gọi là “được bảo vệ” trong các ngôn ngữ khác). Một số lớp được thiết kế để được kế thừa từ đó, để mở rộng hoặc sửa đổi các khía cạnh của hành vi của lớp. Khi thiết kế một lớp như vậy, hãy cẩn thận đưa ra các quyết định rõ ràng về thuộc tính nào là công khai, thuộc tính nào là một phần của API lớp con và thuộc tính nào thực sự chỉ được sử dụng bởi lớp cơ sở của bạn Với suy nghĩ này, đây là hướng dẫn Pythonic
Mọi đảm bảo tương thích ngược chỉ áp dụng cho các giao diện công cộng. Theo đó, điều quan trọng là người dùng có thể phân biệt rõ ràng giữa giao diện công cộng và nội bộ Giao diện tài liệu được coi là công khai, trừ khi tài liệu tuyên bố rõ ràng chúng là giao diện tạm thời hoặc nội bộ được miễn trừ khỏi các đảm bảo tương thích ngược thông thường. Tất cả các giao diện không có giấy tờ nên được coi là nội bộ Để hỗ trợ tốt hơn cho việc xem xét nội tâm, các mô-đun nên khai báo rõ ràng các tên trong API công khai của chúng bằng thuộc tính # 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)06. Đặt # 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)06 thành danh sách trống cho biết mô-đun không có API công khai Ngay cả khi # 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)06 được đặt phù hợp, các giao diện bên trong (gói, mô-đun, lớp, chức năng, thuộc tính hoặc tên khác) vẫn phải được thêm tiền tố bằng một dấu gạch dưới ở đầu Một giao diện cũng được coi là nội bộ nếu bất kỳ không gian chứa tên nào (gói, mô-đun hoặc lớp) được coi là nội bộ Tên đã nhập phải luôn được coi là chi tiết triển khai. Các mô-đun khác không được dựa vào quyền truy cập gián tiếp vào các tên đã nhập đó trừ khi chúng là một phần được ghi rõ ràng trong API của mô-đun chứa, chẳng hạn như mô-đun # 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)59 hoặc mô-đun # 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)35 của gói hiển thị chức năng từ mô-đun con
Với việc chấp nhận PEP 484, các quy tắc kiểu cho chú thích chức năng đã thay đổi
PEP 526 đã giới thiệu các chú thích biến. Các đề xuất kiểu cho chúng tương tự như các đề xuất về chú thích chức năng được mô tả ở trên |