Các phương pháp hay nhất về kiểu mã Python
Python is the main dynamic language used at Google. This style guide is a list of dos and don’ts for Python programs Show
To help you format code correctly, we’ve created a settings file for Vim. For Emacs, the default settings should be fine Many teams use the yapf auto-formatter to avoid arguing over formatting 2 Python Language Rules2. 1 LintRun 18 over your code using this pylintrc2. 1. 1 Definition 18 is a tool for finding bugs and style problems in Python source code. It finds problems that are typically caught by a compiler for less dynamic languages like C and C++. Because of the dynamic nature of Python, some warnings may be incorrect; however, spurious warnings should be fairly infrequent2. 1. 2 ProsCatches easy-to-miss errors like typos, using-vars-before-assignment, etc 2. 1. 3 Cons 18 isn’t perfect. To take advantage of it, sometimes we’ll need to write around it, suppress its warnings or fix it2. 1. 4 DecisionMake sure you run 18 on your codeSuppress warnings if they are inappropriate so that other issues are not hidden. To suppress warnings, you can set a line-level comment
18 warnings are each identified by symbolic name ( 23) Google-specific warnings start with 24If the reason for the suppression is not clear from the symbolic name, add an explanation Suppressing in this way has the advantage that we can easily search for suppressions and revisit them You can get a list of 18 warnings by doingTo get more information on a particular message, use Prefer 26 to the deprecated older form 27Unused argument warnings can be suppressed by deleting the variables at the beginning of the function. Always include a comment explaining why you are deleting it. “Unused. " là đủ. For example
Các hình thức phổ biến khác để loại bỏ cảnh báo này bao gồm sử dụng ' 28' làm mã định danh cho đối số không được sử dụng hoặc thêm tiền tố vào tên đối số bằng ' 29' hoặc gán chúng cho ' 28'. Các hình thức này được cho phép nhưng không còn được khuyến khích. Những trình gọi ngắt này chuyển đối số theo tên và không thực thi rằng đối số thực sự không được sử dụng2. 2 nhập khẩuChỉ sử dụng các câu lệnh 31 cho các gói và mô-đun, không dùng cho các lớp hoặc chức năng riêng lẻ2. 2. 1 DefinitionReusability mechanism for sharing code from one module to another 2. 2. 2 ProsThe namespace management convention is simple. The source of each identifier is indicated in a consistent way; 32 says that object 33 is defined in module 342. 2. 3 ConsModule names can still collide. Some module names are inconveniently long 2. 2. 4 Decision
For example the module 47 may be imported as follows
Do not use relative names in imports. Ngay cả khi mô-đun nằm trong cùng một gói, hãy sử dụng tên gói đầy đủ. This helps prevent unintentionally importing a package twice 2. 2. 4. 1 ExemptionsExemptions from this rule
2. 3 PackagesImport each module using the full pathname location of the module 2. 3. 1 Ưu điểmAvoids conflicts in module names or incorrect imports due to the module search path not being what the author expected. Makes it easier to find modules 2. 3. 2 ConsMakes it harder to deploy code because you have to replicate the package hierarchy. Not really a problem with modern deployment mechanisms 2. 3. 3 DecisionAll new code should import each module by its full package name Imports should be as follows
(assume this file lives in 48 where 49 also exists)
The directory the main binary is located in should not be assumed to be in 50 despite that happening in some environments. This being the case, code should assume that 51 refers to a third party or top level package named 52, not a local 492. 4 ExceptionsExceptions are allowed but must be used carefully 2. 4. 1 DefinitionExceptions are a means of breaking out of normal control flow to handle errors or other exceptional conditions 2. 4. 2 ProsThe control flow of normal operation code is not cluttered by error-handling code. It also allows the control flow to skip multiple frames when a certain condition occurs, e. g. , returning from N nested functions in one step instead of having to plumb error codes through 2. 4. 3 ConsMay cause the control flow to be confusing. Easy to miss error cases when making library calls 2. 4. 4 DecisionExceptions must follow certain conditions
2. 5 Mutable Global StateAvoid mutable global state 2. 5. 1 DefinitionModule level values or class attributes that can get mutated during program execution 2. 5. 2 Ưu điểmOccasionally useful 2. 5. 3 nhược điểm
2. 5. 4 Quyết địnhAvoid mutable global state Trong những trường hợp hiếm hoi khi sử dụng trạng thái toàn cầu được đảm bảo, các thực thể toàn cầu có thể thay đổi phải được khai báo ở cấp độ mô-đun hoặc dưới dạng thuộc tính lớp và được tạo nội bộ bằng cách thêm một _______28 vào tên. Nếu cần, quyền truy cập bên ngoài vào trạng thái toàn cầu có thể thay đổi phải được thực hiện thông qua các hàm công khai hoặc phương thức lớp. Xem bên dưới. Vui lòng giải thích lý do thiết kế tại sao trạng thái chung có thể thay đổi đang được sử dụng trong nhận xét hoặc tài liệu được liên kết từ nhận xét Hằng số cấp mô-đun được cho phép và khuyến khích. Ví dụ. 71 cho hằng số sử dụng nội bộ hoặc 72 cho hằng số API công khai. Các hằng số phải được đặt tên bằng cách sử dụng tất cả các chữ hoa có dấu gạch dưới. Xem bên dưới2. 6 Các lớp và hàm lồng nhau/cục bộ/bên trongNested local functions or classes are fine when used to close over a local variable. Inner classes are fine 2. 6. 1 DefinitionA class can be defined inside of a method, function, or class. A function can be defined inside a method or function. Nested functions have read-only access to variables defined in enclosing scopes 2. 6. 2 ProsAllows definition of utility classes and functions that are only used inside of a very limited scope. Very ADT-y. Commonly used for implementing decorators 2. 6. 3 ConsNested functions and classes cannot be directly tested. Nesting can make the outer function longer and less readable 2. 6. 4 DecisionThey are fine with some caveats. Avoid nested functions or classes except when closing over a local value other than 73 or 74. Do not nest a function just to hide it from users of a module. Instead, prefix its name with an _ at the module level so that it can still be accessed by tests2. 7 cách hiểu và biểu thức trình tạoOkay to use for simple cases 2. 7. 1 DefinitionList, Dict, and Set comprehensions as well as generator expressions provide a concise and efficient way to create container types and iterators without resorting to the use of traditional loops, 75, 76, or 772. 7. 2 ProsViệc hiểu đơn giản có thể rõ ràng và đơn giản hơn các kỹ thuật tạo chính tả, danh sách hoặc tập hợp khác. Biểu thức trình tạo có thể rất hiệu quả, vì chúng tránh hoàn toàn việc tạo danh sách 2. 7. 3 nhược điểmCó thể khó đọc các biểu thức trình tạo hoặc hiểu phức tạp 2. 7. 4 Quyết địnhĐược rồi để sử dụng cho các trường hợp đơn giản. Mỗi phần phải vừa trên một dòng. biểu thức ánh xạ, mệnh đề 78, biểu thức bộ lọc. Nhiều mệnh đề 78 hoặc biểu thức bộ lọc không được phép. Thay vào đó, hãy sử dụng các vòng lặp khi mọi thứ trở nên phức tạp hơn
2. 8 Iterator và Operator mặc địnhSử dụng các trình lặp và toán tử mặc định cho các loại hỗ trợ chúng, như danh sách, từ điển và tệp 2. 8. 1 Định nghĩaCác loại vùng chứa, như từ điển và danh sách, xác định các trình vòng lặp mặc định và toán tử kiểm tra tư cách thành viên (“in” và “not in”) 2. 8. 2 Ưu điểmCác trình vòng lặp và toán tử mặc định rất đơn giản và hiệu quả. Chúng thể hiện thao tác trực tiếp mà không cần gọi thêm phương thức. Một hàm sử dụng các toán tử mặc định là chung chung. Nó có thể được sử dụng với bất kỳ loại nào hỗ trợ hoạt động 2. 8. 3 nhược điểmBạn không thể biết loại đối tượng bằng cách đọc tên phương thức (trừ khi biến có chú thích loại). Đây cũng là một lợi thế 2. 8. 4 Quyết địnhSử dụng các trình lặp và toán tử mặc định cho các loại hỗ trợ chúng, như danh sách, từ điển và tệp. Các loại tích hợp cũng xác định các phương thức lặp. Ưu tiên các phương thức này hơn các phương thức trả về danh sách, ngoại trừ việc bạn không nên thay đổi vùng chứa trong khi lặp lại nó 0 12. 9 máy phát điệnSử dụng máy phát điện khi cần thiết 2. 9. 1 Định nghĩaHàm tạo trả về một trình vòng lặp mang lại một giá trị mỗi khi nó thực thi câu lệnh năng suất. Sau khi nó mang lại một giá trị, trạng thái thời gian chạy của hàm tạo bị tạm dừng cho đến khi cần giá trị tiếp theo 2. 9. 2 Ưu điểmMã đơn giản hơn, vì trạng thái của các biến cục bộ và luồng điều khiển được giữ nguyên cho mỗi cuộc gọi. Trình tạo sử dụng ít bộ nhớ hơn so với hàm tạo toàn bộ danh sách giá trị cùng một lúc 2. 9. 3 nhược điểmCác biến cục bộ trong trình tạo sẽ không được thu gom rác cho đến khi trình tạo bị tiêu thụ đến mức cạn kiệt hoặc chính nó đã được thu gom rác 2. 9. 4 Quyết địnhKhỏe. Sử dụng “Năng suất. ” thay vì “Trả về. ” trong chuỗi tài liệu cho các hàm tạo Nếu trình tạo quản lý một tài nguyên đắt tiền, hãy đảm bảo buộc dọn sạch Một cách hay để dọn dẹp là bọc trình tạo bằng trình quản lý ngữ cảnh PEP-0533 2. 10 Hàm LambdaĐược rồi cho một lớp lót. Thích các biểu thức trình tạo hơn 75 hoặc 76 với một 772. 10. 1 Định nghĩaLambdas định nghĩa các hàm ẩn danh trong một biểu thức, trái ngược với một câu lệnh 2. 10. 2 Ưu điểmTiện lợi 2. 10. 3 nhược điểmKhó đọc và gỡ lỗi hơn các chức năng cục bộ. Việc thiếu tên có nghĩa là dấu vết ngăn xếp khó hiểu hơn. Tính biểu cảm bị hạn chế vì chức năng chỉ có thể chứa một biểu thức 2. 10. 4 Quyết địnhĐược rồi để sử dụng chúng cho một lớp lót. Nếu mã bên trong hàm lambda dài hơn 60-80 ký tự, thì có lẽ tốt hơn nên xác định mã đó là mã thông thường Đối với các hoạt động phổ biến như phép nhân, hãy sử dụng các hàm từ mô-đun 83 thay vì các hàm lambda. Ví dụ: thích 84 hơn là 852. 11 Biểu thức điều kiệnĐược rồi cho các trường hợp đơn giản 2. 11. 1 Định nghĩaBiểu thức điều kiện (đôi khi được gọi là “toán tử bậc ba”) là cơ chế cung cấp cú pháp ngắn hơn cho câu lệnh if. Ví dụ. 862. 11. 2 Ưu điểmShorter and more convenient than an if statement 2. 11. 3 nhược điểmCó thể khó đọc hơn câu lệnh if. Điều kiện có thể khó xác định nếu biểu thức dài 2. 11. 4 Quyết địnhĐược rồi để sử dụng cho các trường hợp đơn giản. Mỗi phần phải vừa trên một dòng. biểu thức đúng, biểu thức if, biểu thức khác. Sử dụng câu lệnh if hoàn chỉnh khi mọi thứ trở nên phức tạp hơn 2 32. 12 giá trị đối số mặc địnhĐược rồi trong hầu hết các trường hợp 2. 12. 1 Định nghĩaBạn có thể chỉ định giá trị cho các biến ở cuối danh sách tham số của hàm, chẳng hạn như. g. , 87. Nếu 88 được gọi chỉ với một đối số, thì 89 được đặt thành 0. Nếu nó được gọi với hai đối số, thì 89 có giá trị của đối số thứ hai2. 12. 2 Ưu điểmThường thì bạn có một hàm sử dụng nhiều giá trị mặc định, nhưng trong một số trường hợp hiếm hoi, bạn muốn ghi đè lên các giá trị mặc định. Default argument values provide an easy way to do this, without having to define lots of functions for the rare exceptions. As Python does not support overloaded methods/functions, default arguments are an easy way of “faking” the overloading behavior 2. 12. 3 ConsCác đối số mặc định được đánh giá một lần tại thời điểm tải mô-đun. Điều này có thể gây ra sự cố nếu đối số là đối tượng có thể thay đổi, chẳng hạn như danh sách hoặc từ điển. Nếu chức năng sửa đổi đối tượng (e. g. , by appending an item to a list), the default value is modified 2. 12. 4 Quyết địnhĐược rồi để sử dụng với cảnh báo sau Không sử dụng các đối tượng có thể thay đổi làm giá trị mặc định trong định nghĩa hàm hoặc phương thức 4 52. 13 thuộc tínhCác thuộc tính có thể được sử dụng để kiểm soát việc nhận hoặc thiết lập các thuộc tính yêu cầu tính toán hoặc logic thông thường. Việc triển khai thuộc tính phải phù hợp với kỳ vọng chung của quyền truy cập thuộc tính thông thường. rằng chúng rẻ, đơn giản và không gây ngạc nhiên 2. 13. 1 Định nghĩaMột cách để gói các cuộc gọi phương thức để nhận và đặt thuộc tính làm quyền truy cập thuộc tính tiêu chuẩn 2. 13. 2 Ưu điểm
2. 13. 3 nhược điểm
2. 13. 4 Quyết địnhCác thuộc tính được cho phép, nhưng, giống như quá tải toán tử, chỉ nên được sử dụng khi cần thiết và phù hợp với mong đợi của truy cập thuộc tính điển hình; Ví dụ: không được phép sử dụng một thuộc tính để lấy và đặt một thuộc tính nội bộ. không có tính toán xảy ra, vì vậy thuộc tính là không cần thiết (). Trong khi đó, việc sử dụng một thuộc tính để kiểm soát quyền truy cập thuộc tính hoặc để tính toán một giá trị có nguồn gốc tầm thường được cho phép. logic rất đơn giản và không có gì đáng ngạc nhiên Các thuộc tính nên được tạo bằng 91. Thực hiện thủ công một bộ mô tả thuộc tính được coi là mộtKế thừa với các thuộc tính có thể không rõ ràng. Không sử dụng các thuộc tính để thực hiện tính toán mà một lớp con có thể muốn ghi đè và mở rộng 2. 14 Đánh giá Đúng/SaiSử dụng sai "ngầm" nếu có thể 2. 14. 1 Định nghĩaPython đánh giá các giá trị nhất định là 92 khi ở trong ngữ cảnh boolean. Một "quy tắc ngón tay cái" nhanh là tất cả các giá trị "trống rỗng" đều được coi là sai, vì vậy, ________93 tất cả đều được đánh giá là sai trong ngữ cảnh boolean2. 14. 2 Ưu điểmCác điều kiện sử dụng booleans Python dễ đọc hơn và ít bị lỗi hơn. Trong hầu hết các trường hợp, chúng cũng nhanh hơn 2. 14. 3 nhược điểmCó thể trông lạ đối với các nhà phát triển C/C++ 2. 14. 4 Quyết địnhSử dụng sai “ngầm” nếu có thể, e. g. , 94 thay vì 95. Có một vài cảnh báo mà bạn nên ghi nhớ mặc dù
2. 16 Phạm vi từ vựngĐược rồi để sử dụng 2. 16. 1 Định nghĩaMột hàm Python lồng nhau có thể tham chiếu đến các biến được xác định trong các hàm kèm theo, nhưng không thể gán cho chúng. Các liên kết biến được giải quyết bằng cách sử dụng phạm vi từ vựng, nghĩa là dựa trên văn bản chương trình tĩnh. Bất kỳ sự gán nào cho một tên trong một khối sẽ khiến Python coi tất cả các tham chiếu đến tên đó là một biến cục bộ, ngay cả khi việc sử dụng có trước sự gán. Nếu một khai báo toàn cầu xảy ra, tên được coi là một biến toàn cầu Một ví dụ về việc sử dụng tính năng này là 82. 16. 2 Ưu điểmThường dẫn đến mã rõ ràng hơn, thanh lịch hơn. Đặc biệt an ủi các lập trình viên Lisp và Scheme (và Haskell, ML và…) có kinh nghiệm 2. 16. 3 nhược điểmCó thể dẫn đến các lỗi khó hiểu. Chẳng hạn như ví dụ này dựa trên PEP-0227 9Vì vậy, 17 sẽ in ra 18, không phải là 192. 16. 4 Quyết địnhĐược rồi để sử dụng 2. 17 Trình trang trí chức năng và phương thứcSử dụng decorators một cách thận trọng khi có một lợi thế rõ ràng. Tránh 20 và hạn chế sử dụng 212. 17. 1 Định nghĩa(Một. k. một “ký hiệu 22”). Một trình trang trí phổ biến là 91, được sử dụng để chuyển đổi các phương thức thông thường thành các thuộc tính được tính toán động. Tuy nhiên, cú pháp của trình trang trí cũng cho phép các trình trang trí do người dùng định nghĩa. Cụ thể, đối với một số chức năng 24, điều này 0tương đương với 12. 17. 2 Ưu điểmChỉ định một cách trang nhã một số chuyển đổi trên một phương thức; 2. 17. 3 nhược điểmTrình trang trí có thể thực hiện các thao tác tùy ý trên đối số của hàm hoặc trả về giá trị, dẫn đến hành vi ngầm đáng ngạc nhiên. Ngoài ra, các trình trang trí thực thi tại thời điểm xác định đối tượng. Đối với các đối tượng cấp mô-đun (lớp, chức năng mô-đun,…) điều này xảy ra tại thời điểm nhập. Lỗi trong mã trang trí hầu như không thể phục hồi từ 2. 17. 4 Quyết địnhSử dụng decorators một cách thận trọng khi có một lợi thế rõ ràng. Người trang trí phải tuân theo các nguyên tắc nhập và đặt tên giống như các chức năng. Trình trang trí pydoc phải nêu rõ rằng chức năng này là một trình trang trí. Viết bài kiểm tra đơn vị cho người trang trí Tránh các phụ thuộc bên ngoài trong chính trình trang trí (e. g. không dựa vào tệp, ổ cắm, kết nối cơ sở dữ liệu, v.v. ), vì chúng có thể không khả dụng khi trình trang trí chạy (tại thời điểm nhập, có thể từ 25 hoặc các công cụ khác). Một trình trang trí được gọi với các tham số hợp lệ phải (càng nhiều càng tốt) được đảm bảo thành công trong mọi trường hợpTrình trang trí là trường hợp đặc biệt của “mã cấp cao nhất” - xem để thảo luận thêm Không bao giờ sử dụng 20 trừ khi bị buộc phải tích hợp với API được xác định trong thư viện hiện có. Thay vào đó hãy viết một hàm cấp mô-đunChỉ sử dụng 21 khi viết một hàm tạo có tên hoặc một quy trình dành riêng cho lớp để sửa đổi trạng thái chung cần thiết, chẳng hạn như bộ đệm trên toàn quy trình2. 18 luồngKhông dựa vào tính nguyên tử của các loại tích hợp Mặc dù các kiểu dữ liệu tích hợp sẵn của Python, chẳng hạn như từ điển, dường như có các hoạt động nguyên tử, nhưng có một số trường hợp chúng không phải là nguyên tử (e. g. nếu 28 hoặc 29 được triển khai dưới dạng phương thức Python) và không nên dựa vào tính nguyên tử của chúng. Bạn cũng không nên dựa vào phép gán biến nguyên tử (vì điều này lại phụ thuộc vào từ điển)Sử dụng kiểu dữ liệu 30 của mô-đun Hàng đợi làm cách ưu tiên để giao tiếp dữ liệu giữa các luồng. Nếu không, hãy sử dụng mô-đun luồng và các nguyên hàm khóa của nó. Ưu tiên các biến điều kiện và 31 thay vì sử dụng các khóa cấp thấp hơn2. 19 Tính năng nguồnTránh các tính năng này 2. 19. 1 Định nghĩaPython là một ngôn ngữ cực kỳ linh hoạt và cung cấp cho bạn nhiều tính năng ưa thích như siêu dữ liệu tùy chỉnh, quyền truy cập vào mã byte, biên dịch nhanh, kế thừa động, sửa chữa đối tượng, hack nhập, phản chiếu (e. g. một số cách sử dụng của 32), sửa đổi bên trong hệ thống, phương pháp 33 thực hiện dọn dẹp tùy chỉnh, v.v.2. 19. 2 Ưu điểmĐây là những tính năng ngôn ngữ mạnh mẽ. Họ có thể làm cho mã của bạn gọn hơn 2. 19. 3 nhược điểmRất hấp dẫn khi sử dụng những tính năng “hay ho” này khi chúng không thực sự cần thiết. Khó đọc, hiểu và gỡ lỗi mã đang sử dụng các tính năng bất thường bên dưới. Thoạt đầu có vẻ không phải như vậy (đối với tác giả gốc), nhưng khi xem lại mã, nó có xu hướng khó hơn mã dài hơn nhưng đơn giản 2. 19. 4 Quyết địnhTránh các tính năng này trong mã của bạn Các mô-đun và lớp thư viện tiêu chuẩn sử dụng nội bộ các tính năng này đều được phép sử dụng (ví dụ: 34, 35 và 36)2. 20 con trăn hiện đại. từ __future__ nhập khẩuCác thay đổi ngữ nghĩa của phiên bản ngôn ngữ mới có thể được kiểm soát sau quá trình nhập đặc biệt trong tương lai để kích hoạt chúng trên cơ sở từng tệp trong thời gian chạy trước đó 2. 20. 1 Định nghĩaCó thể bật một số tính năng hiện đại hơn thông qua câu lệnh 37 cho phép sử dụng sớm các tính năng từ các phiên bản Python dự kiến trong tương lai2. 20. 2 Ưu điểmĐiều này đã được chứng minh là giúp nâng cấp phiên bản thời gian chạy mượt mà hơn vì các thay đổi có thể được thực hiện trên cơ sở từng tệp trong khi khai báo tính tương thích và ngăn chặn hồi quy trong các tệp đó. Mã hiện đại dễ bảo trì hơn vì ít có khả năng tích lũy nợ kỹ thuật sẽ gây ra sự cố trong quá trình nâng cấp thời gian chạy trong tương lai 2. 20. 3 nhược điểmMã như vậy có thể không hoạt động trên các phiên bản thông dịch viên rất cũ trước khi đưa ra câu lệnh tương lai cần thiết. Nhu cầu này phổ biến hơn trong các dự án hỗ trợ rất nhiều môi trường 2. 20. 4 Quyết địnhtừ __future__ nhập khẩuViệc sử dụng các câu lệnh 37 được khuyến khích. Nó cho phép một tệp nguồn nhất định bắt đầu sử dụng các tính năng cú pháp Python hiện đại hơn ngày nay. Sau khi bạn không còn cần chạy trên phiên bản mà các tính năng bị ẩn đằng sau lần nhập 39, vui lòng xóa các dòng đóTrong mã có thể thực thi trên các phiên bản cũ như 3. 5 thay vì >= 3. 7, nhập khẩu 2Để biết thêm thông tin, hãy đọc tài liệu định nghĩa câu lệnh tương lai của Python Vui lòng không xóa các mục nhập này cho đến khi bạn tin rằng mã này chỉ được sử dụng trong một môi trường đủ hiện đại. Ngay cả khi bạn hiện không sử dụng tính năng mà một tính năng nhập cụ thể trong tương lai cho phép trong mã của bạn hôm nay, thì việc giữ nguyên tính năng này trong tệp sẽ ngăn việc vô tình sửa đổi mã sau này tùy thuộc vào hành vi cũ hơn Sử dụng các câu lệnh nhập khẩu 40 khác khi bạn thấy phù hợp2. 21 Loại mã chú thíchBạn có thể chú thích mã Python bằng gợi ý loại theo PEP-484 và kiểm tra loại mã khi xây dựng bằng công cụ kiểm tra loại như pytype Loại chú thích có thể trong nguồn hoặc trong một. Bất cứ khi nào có thể, chú thích nên ở trong nguồn. Sử dụng tệp pyi cho bên thứ ba hoặc mô-đun mở rộng 2. 21. 1 Định nghĩaChú thích kiểu (hoặc "gợi ý kiểu") dành cho hàm hoặc đối số phương thức và giá trị trả về 3Bạn cũng có thể khai báo loại biến bằng cú pháp PEP-526 tương tự 2. 21. 2 Ưu điểmLoại chú thích cải thiện khả năng đọc và bảo trì mã của bạn. Trình kiểm tra loại sẽ chuyển đổi nhiều lỗi thời gian chạy thành lỗi thời gian xây dựng và giảm khả năng sử dụng của bạn 2. 21. 3 nhược điểmBạn sẽ phải cập nhật các khai báo kiểu. Bạn có thể thấy lỗi loại mà bạn nghĩ là mã hợp lệ. Việc sử dụng bộ kiểm tra loại có thể làm giảm khả năng sử dụng của bạn 2. 21. 4 Quyết địnhBạn được khuyến khích bật phân tích kiểu Python khi cập nhật mã. Khi thêm hoặc sửa đổi API công khai, hãy bao gồm các chú thích loại và cho phép kiểm tra qua pytype trong hệ thống xây dựng. Vì phân tích tĩnh còn tương đối mới đối với Python, chúng tôi thừa nhận rằng các tác dụng phụ không mong muốn (chẳng hạn như các loại được suy luận sai) có thể ngăn một số dự án áp dụng. Trong những trường hợp đó, tác giả được khuyến khích thêm nhận xét bằng TODO hoặc liên kết đến lỗi mô tả (các) sự cố hiện đang ngăn cản việc áp dụng chú thích loại trong tệp BUILD hoặc trong chính mã khi thích hợp 3 quy tắc kiểu Python3. 1 dấu chấm phẩyKhông kết thúc dòng của bạn bằng dấu chấm phẩy và không sử dụng dấu chấm phẩy để đặt hai câu lệnh trên cùng một dòng 3. 2 Chiều dài dòngĐộ dài dòng tối đa là 80 ký tự Ngoại lệ rõ ràng đối với giới hạn 80 ký tự
Không sử dụng tiếp tục dòng gạch chéo ngược ngoại trừ câu lệnh 42 yêu cầu ba trình quản lý ngữ cảnh trở lênTận dụng Python. Nếu cần, bạn có thể thêm một cặp dấu ngoặc đơn xung quanh một biểu thức 4Khi một chuỗi ký tự không vừa trên một dòng, hãy sử dụng dấu ngoặc đơn để nối dòng ẩn 5Trong các nhận xét, hãy đặt các URL dài trên dòng riêng của chúng nếu cần 6 7Có thể sử dụng tiếp tục dấu gạch chéo ngược khi xác định câu lệnh 42 với ba trình quản lý ngữ cảnh trở lên. Đối với hai trình quản lý bối cảnh, hãy sử dụng câu lệnh 42 lồng nhau 8 9 0Lưu ý về sự thụt đầu dòng của các phần tử trong các ví dụ tiếp tục dòng ở trên; Trong tất cả các trường hợp khác khi một dòng vượt quá 80 ký tự và trình định dạng tự động yapf không giúp đưa dòng xuống dưới giới hạn, thì dòng đó được phép vượt quá mức tối đa này. Các tác giả được khuyến khích ngắt dòng theo cách thủ công theo ghi chú ở trên khi thấy hợp lý 3. 3 dấu ngoặc đơnSử dụng dấu ngoặc đơn một cách tiết kiệm Nó là tốt, mặc dù không bắt buộc, để sử dụng dấu ngoặc đơn xung quanh bộ dữ liệu. Không sử dụng chúng trong các câu lệnh trả về hoặc câu lệnh có điều kiện trừ khi sử dụng dấu ngoặc đơn để tiếp tục dòng ngụ ý hoặc để chỉ ra một bộ 1 23. 4 Thụt đầu dòngThụt lề các khối mã của bạn với 4 dấu cách Không bao giờ sử dụng các tab. Việc tiếp tục dòng ngụ ý phải căn chỉnh các phần tử được bao theo chiều dọc (xem) hoặc sử dụng thụt lề 4 dấu cách treo. Dấu ngoặc đóng (tròn, vuông hoặc cong) có thể được đặt ở cuối biểu thức hoặc trên các dòng riêng biệt, nhưng sau đó phải được thụt vào giống như dòng có dấu ngoặc mở tương ứng 3 43. 4. 1 Dấu phẩy ở cuối dãy các mục?Dấu phẩy ở cuối trong chuỗi các mục chỉ được khuyến nghị khi mã thông báo vùng chứa đóng 45, 46 hoặc 47 không xuất hiện trên cùng một dòng với phần tử cuối cùng. Sự hiện diện của dấu phẩy ở cuối cũng được sử dụng như một gợi ý cho trình định dạng tự động mã Python YAPF của chúng tôi để hướng dẫn nó tự động định dạng vùng chứa các mục thành một mục trên mỗi dòng khi có _ 48 sau phần tử cuối cùng 53. 5 dòng trốngHai dòng trống giữa các định nghĩa cấp cao nhất, có thể là định nghĩa hàm hoặc lớp. Một dòng trống giữa các định nghĩa phương thức và giữa chuỗi tài liệu của 49 và phương thức đầu tiên. Không có dòng trống nào sau dòng 50. Sử dụng các dòng trống đơn khi bạn đánh giá phù hợp trong các hàm hoặc phương thứcCác dòng trống không cần phải được neo vào định nghĩa. Ví dụ: các nhận xét liên quan ngay trước các định nghĩa hàm, lớp và phương thức có thể có ý nghĩa. Cân nhắc xem nhận xét của bạn có thể hữu ích hơn như một phần của chuỗi tài liệu không 3. 6 Khoảng trắngThực hiện theo các quy tắc đánh máy tiêu chuẩn để sử dụng khoảng trắng xung quanh dấu chấm câu Không có khoảng trắng bên trong dấu ngoặc đơn, dấu ngoặc hoặc dấu ngoặc nhọn 6 7Không có khoảng trắng trước dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm. Sử dụng khoảng trắng sau dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm, ngoại trừ ở cuối dòng 8 9Không có khoảng trắng trước dấu ngoặc đơn/ngoặc mở bắt đầu danh sách đối số, lập chỉ mục hoặc cắt 0 1Không có khoảng trắng ở cuối Bao quanh các toán tử nhị phân với một khoảng trắng ở hai bên để gán ( 51), so sánh ( 52) và Booleans ( 53). Sử dụng khả năng phán đoán tốt hơn của bạn để chèn khoảng trắng xung quanh các toán tử số học ( 54, 55, 56, 57, 58, 59, 60, 22)Không bao giờ sử dụng khoảng trắng xung quanh 51 khi chuyển đối số từ khóa hoặc xác định giá trị tham số mặc định, với một ngoại lệ. , hãy sử dụng khoảng trắng xung quanh 51 cho giá trị tham số mặc định 2 3Không sử dụng khoảng trắng để sắp xếp theo chiều dọc các mã thông báo trên các dòng liên tiếp, vì nó sẽ trở thành gánh nặng bảo trì (áp dụng cho 64, 65, 51, v.v. ) 4 53. 7 dòng ShebangHầu hết các tệp 67 không cần bắt đầu bằng dòng 68. Bắt đầu tệp chính của chương trình với 69 (để hỗ trợ virtualenv) hoặc 70 mỗi PEP-394Dòng này được nhân sử dụng để tìm trình thông dịch Python, nhưng bị Python bỏ qua khi nhập mô-đun. Nó chỉ cần thiết trên một tệp dự định được thực thi trực tiếp Đảm bảo sử dụng đúng kiểu cho mô-đun, hàm, chuỗi tài liệu phương thức và nhận xét nội tuyến 3. 8. 1 tài liệuPython sử dụng docstrings để viết mã tài liệu. Chuỗi tài liệu là một chuỗi là câu lệnh đầu tiên trong gói, mô-đun, lớp hoặc hàm. Các chuỗi này có thể được trích xuất tự động thông qua thành viên 71 của đối tượng và được sử dụng bởi 25. (Hãy thử chạy 25 trên mô-đun của bạn để xem nó trông như thế nào. ) Luôn sử dụng định dạng ba trích dẫn kép 74 cho các chuỗi tài liệu (theo PEP 257). Chuỗi tài liệu phải được tổ chức dưới dạng một dòng tóm tắt (một dòng vật lý không quá 80 ký tự) được kết thúc bằng dấu chấm, dấu chấm hỏi hoặc dấu chấm than. Khi viết thêm (khuyến khích), dòng này phải được theo sau bởi một dòng trống, tiếp theo là phần còn lại của chuỗi tài liệu bắt đầu ở cùng vị trí con trỏ với trích dẫn đầu tiên của dòng đầu tiên. Có nhiều hướng dẫn định dạng hơn cho các tài liệu bên dưới3. 8. 2 mô-đunMỗi tệp phải chứa giấy phép soạn sẵn. Chọn bản soạn sẵn thích hợp cho giấy phép được dự án sử dụng (ví dụ: Apache 2. 0, BSD, LGPL, GPL) Các tệp phải bắt đầu bằng một chuỗi tài liệu mô tả nội dung và cách sử dụng mô-đun 63. 8. 2. 1 mô-đun thử nghiệmKhông bắt buộc phải có chuỗi tài liệu cấp mô-đun cho các tệp thử nghiệm. Chúng chỉ nên được đưa vào khi có thông tin bổ sung có thể được cung cấp Các ví dụ bao gồm một số chi tiết cụ thể về cách chạy thử nghiệm, giải thích về mẫu thiết lập bất thường, sự phụ thuộc vào môi trường bên ngoài, v.v. 7Không nên sử dụng các chuỗi tài liệu không cung cấp bất kỳ thông tin mới nào 3. 8. 3 Hàm và Phương thứcTrong phần này, "hàm" có nghĩa là một phương thức, chức năng, trình tạo hoặc thuộc tính Một chuỗi tài liệu là bắt buộc đối với mọi chức năng có một hoặc nhiều thuộc tính sau
Một chuỗi tài liệu phải cung cấp đủ thông tin để viết lệnh gọi đến hàm mà không cần đọc mã của hàm. Chuỗi tài liệu phải mô tả cú pháp gọi của hàm và ngữ nghĩa của nó, nhưng nói chung không phải là chi tiết triển khai của nó, trừ khi những chi tiết đó có liên quan đến cách sử dụng hàm. Ví dụ: một hàm thay đổi một trong các đối số của nó dưới dạng tác dụng phụ cần lưu ý rằng trong chuỗi tài liệu của nó. Mặt khác, các chi tiết tinh tế nhưng quan trọng về việc triển khai chức năng không liên quan đến người gọi sẽ được thể hiện dưới dạng nhận xét bên cạnh mã tốt hơn là trong chuỗi tài liệu của chức năng Chuỗi tài liệu có thể là kiểu mô tả ( 75) hoặc kiểu mệnh lệnh ( 76), nhưng kiểu này phải nhất quán trong một tệp. Chuỗi tài liệu cho bộ mô tả dữ liệu 91 nên sử dụng cùng kiểu với chuỗi tài liệu cho một thuộc tính hoặc ( 78, thay vì 79)Một phương thức ghi đè một phương thức từ lớp cơ sở có thể có một chuỗi tài liệu đơn giản gửi trình đọc đến chuỗi tài liệu của phương thức được ghi đè, chẳng hạn như 80. Cơ sở lý luận là không cần phải lặp lại ở nhiều nơi tài liệu đã có trong chuỗi tài liệu của phương thức cơ sở. Tuy nhiên, nếu hành vi của phương thức ghi đè về cơ bản khác với phương thức bị ghi đè hoặc cần cung cấp thông tin chi tiết (e. g. , ghi lại các tác dụng phụ bổ sung), một chuỗi tài liệu có ít nhất những điểm khác biệt đó là bắt buộc đối với phương thức ghi đèMột số khía cạnh của một chức năng nên được ghi lại trong các phần đặc biệt, được liệt kê bên dưới. Mỗi phần bắt đầu bằng một dòng tiêu đề, kết thúc bằng dấu hai chấm. Tất cả các phần không phải là tiêu đề nên duy trì thụt lề treo hai hoặc bốn khoảng trắng (nhất quán trong một tệp). Các phần này có thể được bỏ qua trong trường hợp tên và chữ ký của hàm đủ thông tin để có thể mô tả chính xác bằng cách sử dụng chuỗi tài liệu một dòng Liệt kê từng tham số theo tên. Mô tả phải theo sau tên và được phân tách bằng dấu hai chấm, sau đó là khoảng trắng hoặc xuống dòng. Nếu mô tả quá dài để vừa với một dòng 80 ký tự, hãy sử dụng thụt lề treo nhiều hơn 2 hoặc 4 khoảng trắng so với tên tham số (nhất quán với phần còn lại của chuỗi tài liệu trong tệp). Mô tả phải bao gồm (các) loại bắt buộc nếu mã không chứa chú thích loại tương ứng. Nếu một hàm chấp nhận 81 (danh sách đối số có độ dài thay đổi) và/hoặc 82 (đối số từ khóa tùy ý), thì chúng phải được liệt kê là 81 và 82. Mô tả loại và ngữ nghĩa của giá trị trả về. Nếu hàm chỉ trả về Không thì không cần phần này. Nó cũng có thể được bỏ qua nếu chuỗi tài liệu bắt đầu bằng Returns hoặc Yields (e. g. 85) và câu mở đầu đủ để mô tả giá trị trả về. Không bắt chước 'kiểu NumPy' (ví dụ), kiểu này thường ghi lại giá trị trả về của bộ dữ liệu như thể đó là nhiều giá trị trả về với các tên riêng lẻ (không bao giờ đề cập đến bộ dữ liệu). Thay vào đó, hãy mô tả một giá trị trả về như. “Trả về. Một bộ (mat_a, mat_b), trong đó mat_a là …, và…”. Các tên phụ trợ trong chuỗi tài liệu không nhất thiết phải tương ứng với bất kỳ tên nội bộ nào được sử dụng trong thân hàm (vì chúng không phải là một phần của API). Liệt kê tất cả các ngoại lệ có liên quan đến giao diện theo sau là mô tả. Sử dụng tên ngoại lệ tương tự + dấu hai chấm + dấu cách hoặc dòng mới và kiểu thụt lề treo như được mô tả trong Args. Bạn không nên ghi lại các trường hợp ngoại lệ được nêu ra nếu API được chỉ định trong chuỗi tài liệu bị vi phạm (vì điều này nghịch lý sẽ tạo ra hành vi vi phạm phần API của API) 8Tương tự, biến thể này trên 86 với ngắt dòng cũng được cho phép 93. 8. 4 lớpCác lớp nên có một chuỗi tài liệu bên dưới định nghĩa lớp mô tả lớp. Nếu lớp của bạn có các thuộc tính công khai, chúng phải được ghi lại ở đây trong phần 87 và tuân theo cùng định dạng như phần 0Tất cả các chuỗi tài liệu lớp phải bắt đầu bằng một bản tóm tắt một dòng mô tả nội dung mà thể hiện của lớp đại diện. Điều này ngụ ý rằng các lớp con của 60 cũng nên mô tả nội dung của ngoại lệ chứ không phải bối cảnh mà ngoại lệ đó có thể xảy ra. Chuỗi tài liệu lớp không được lặp lại thông tin không cần thiết, chẳng hạn như lớp là một lớp 1 23. 8. 5 Khối và Nhận xét Nội tuyếnNơi cuối cùng để có nhận xét là ở những phần phức tạp của mã. Nếu bạn phải giải thích nó trong lần đánh giá mã tiếp theo, bạn nên bình luận ngay bây giờ. Các hoạt động phức tạp nhận được một vài dòng nhận xét trước khi các hoạt động bắt đầu. Những người không rõ ràng nhận được bình luận ở cuối dòng 3Để cải thiện mức độ dễ đọc, các nhận xét này phải bắt đầu cách mã ít nhất 2 khoảng trắng với ký tự nhận xét 65, theo sau là ít nhất một khoảng trắng trước văn bản của chính nhận xét đóMặt khác, không bao giờ mô tả mã. Giả sử người đọc mã biết Python (mặc dù không phải thứ bạn đang cố gắng làm) tốt hơn bạn 43. 8. 6 Dấu câu, Chính tả và Ngữ phápChú ý đến dấu câu, chính tả và ngữ pháp; Nhận xét phải dễ đọc như văn bản tường thuật, với cách viết hoa và dấu câu thích hợp. Trong nhiều trường hợp, các câu hoàn chỉnh dễ đọc hơn các đoạn câu. Các chú thích ngắn hơn, chẳng hạn như chú thích ở cuối dòng mã, đôi khi có thể kém trang trọng hơn, nhưng bạn nên nhất quán với phong cách của mình Mặc dù có thể khó chịu khi người đánh giá mã chỉ ra rằng bạn đang sử dụng dấu phẩy trong khi lẽ ra bạn nên sử dụng dấu chấm phẩy, nhưng điều rất quan trọng là mã nguồn phải duy trì mức độ rõ ràng và dễ đọc cao. Dấu chấm câu, chính tả và ngữ pháp phù hợp giúp đạt được mục tiêu đó 3. 10 DâySử dụng toán tử , 59 hoặc phương pháp 92 để định dạng chuỗi, ngay cả khi các tham số đều là chuỗi. Sử dụng phán đoán tốt nhất của bạn để quyết định giữa các tùy chọn định dạng chuỗi. Một liên kết duy nhất với 54 thì được nhưng không định dạng với 54 5 6Tránh sử dụng các toán tử 54 và 96 để tích lũy một chuỗi trong một vòng lặp. Trong một số điều kiện, tích lũy một chuỗi với phép cộng có thể dẫn đến thời gian chạy bậc hai thay vì tuyến tính. Mặc dù các tích lũy phổ biến thuộc loại này có thể được tối ưu hóa trên CPython, nhưng đó là chi tiết triển khai. Các điều kiện áp dụng tối ưu hóa không dễ dự đoán và có thể thay đổi. Thay vào đó, hãy thêm từng chuỗi con vào danh sách và 97 danh sách sau khi vòng lặp kết thúc hoặc ghi từng chuỗi con vào bộ đệm 98. Các kỹ thuật này luôn có độ phức tạp thời gian chạy tuyến tính được khấu hao 7 8Hãy nhất quán với sự lựa chọn của bạn về ký tự trích dẫn chuỗi trong một tệp. Chọn 99 hoặc 00 và gắn bó với nó. Bạn có thể sử dụng ký tự trích dẫn khác trên một chuỗi để tránh phải ký tự trích dẫn thoát dấu gạch chéo ngược trong chuỗi 9 0Thích 74 cho các chuỗi nhiều dòng hơn là 02. Các dự án có thể chọn sử dụng 02 cho tất cả các chuỗi nhiều dòng không phải chuỗi doc nếu và chỉ khi chúng cũng sử dụng 99 cho các chuỗi thông thường. Docstrings phải sử dụng 74 bất kểCác chuỗi nhiều dòng không chạy với phần thụt đầu dòng của phần còn lại của chương trình. Nếu bạn cần tránh nhúng thêm khoảng trắng vào chuỗi, hãy sử dụng chuỗi một dòng được nối hoặc chuỗi nhiều dòng để xóa khoảng trắng ban đầu trên mỗi dòng 1 2 3 4 53. 10. 1 nhật kýĐối với các chức năng ghi nhật ký yêu cầu một chuỗi mẫu (với %-placeholders) làm đối số đầu tiên của chúng. Luôn gọi chúng bằng một chuỗi ký tự (không phải chuỗi f. ) làm đối số đầu tiên của chúng với tham số mẫu làm đối số tiếp theo. Một số triển khai ghi nhật ký thu thập chuỗi mẫu chưa được mở rộng dưới dạng trường có thể truy vấn. Nó cũng ngăn việc dành thời gian hiển thị thông báo mà không có trình ghi nhật ký nào được định cấu hình để xuất 6 7 83. 10. 2 thông báo lỗiThông báo lỗi (chẳng hạn như. chuỗi thông báo về các trường hợp ngoại lệ như 54 hoặc thông báo được hiển thị cho người dùng) phải tuân theo ba nguyên tắc
9 03. 11 Tệp, Ổ cắm và Tài nguyên có trạng thái tương tựĐóng các tệp và ổ cắm một cách rõ ràng khi hoàn thành với chúng. Quy tắc này tự nhiên mở rộng cho các tài nguyên có thể đóng sử dụng ổ cắm bên trong, chẳng hạn như kết nối cơ sở dữ liệu và cả các tài nguyên khác cần được đóng theo cách tương tự. Chỉ kể tên một vài ví dụ, điều này cũng bao gồm ánh xạ mmap, đối tượng Tệp h5py và matplotlib. cửa sổ hình pyplot Để các tệp, ổ cắm hoặc các đối tượng trạng thái khác mở một cách không cần thiết có nhiều nhược điểm
Hơn nữa, trong khi các tệp và ổ cắm (và một số tài nguyên hoạt động tương tự) tự động đóng khi đối tượng bị hủy, thì việc ghép thời gian tồn tại của đối tượng với trạng thái của tài nguyên là một cách làm kém.
Việc dựa vào các công cụ hoàn thiện để thực hiện dọn dẹp tự động có các tác dụng phụ có thể quan sát được đã được khám phá lại nhiều lần để dẫn đến các vấn đề lớn, qua nhiều thập kỷ và nhiều ngôn ngữ (xem e. g. bài viết này cho Java) Cách ưu tiên để quản lý tệp và các tài nguyên tương tự là sử dụng 1Đối với các đối tượng giống như tệp không hỗ trợ câu lệnh 42, hãy sử dụng 11 2Trong những trường hợp hiếm hoi khi quản lý tài nguyên dựa trên ngữ cảnh là không khả thi, tài liệu mã phải giải thích rõ ràng cách quản lý thời gian tồn tại của tài nguyên Sử dụng 12 nhận xét cho mã tạm thời, giải pháp ngắn hạn hoặc đủ tốt nhưng không hoàn hảoMột nhận xét 12 bắt đầu bằng từ 12 viết hoa toàn bộ và một mã định danh ngữ cảnh được đặt trong ngoặc đơn. Lý tưởng nhất là tham chiếu lỗi, đôi khi là tên người dùng. Một tài liệu tham khảo lỗi như 15 là thích hợp hơn, bởi vì các lỗi được theo dõi và có các nhận xét tiếp theo, trong khi các cá nhân di chuyển xung quanh và có thể mất ngữ cảnh theo thời gian. 12 được theo sau bởi một lời giải thích về những việc phải làmMục đích là để có một định dạng 12 nhất quán có thể được tìm kiếm để tìm hiểu cách biết thêm chi tiết. 12 không phải là cam kết rằng người được giới thiệu sẽ khắc phục vấn đề. Do đó, khi bạn tạo một 12 với tên người dùng, thì hầu như tên người dùng của bạn luôn được cung cấp 3Nếu 12 của bạn thuộc dạng “Vào một ngày trong tương lai, hãy làm điều gì đó”, hãy đảm bảo rằng bạn bao gồm một ngày cụ thể (“Khắc phục trước tháng 11 năm 2009”) hoặc một sự kiện rất cụ thể (“Xóa mã này khi tất cả khách hàng có thể xử lý phản hồi XML. ”) mà những người bảo trì mã trong tương lai sẽ hiểu3. 13 Nhập định dạngNhập khẩu nên được trên các dòng riêng biệt; E. g 4Các mục nhập luôn được đặt ở đầu tệp, ngay sau bất kỳ nhận xét và chuỗi tài liệu nào của mô-đun cũng như trước các hằng số và toàn cầu của mô-đun. Nhập khẩu nên được nhóm từ chung chung nhất đến ít chung chung nhất
Trong mỗi nhóm, các mục nhập phải được sắp xếp theo từ điển, bỏ qua trường hợp, theo đường dẫn gói đầy đủ của từng mô-đun (_______33_______23 trong ____33_______24). Mã có thể tùy chọn đặt một dòng trống giữa các phần nhập 83. 14 Tuyên bốNói chung chỉ có một tuyên bố trên mỗi dòng Tuy nhiên, bạn chỉ có thể đặt kết quả của một bài kiểm tra trên cùng một dòng với bài kiểm tra nếu toàn bộ câu lệnh nằm trên một dòng. Đặc biệt, bạn không bao giờ có thể làm như vậy với 63/ 64 vì 63 và 64 không thể vừa trên cùng một dòng và bạn chỉ có thể làm như vậy với 29 nếu không có 30 93. 15 Getters và SettersCác hàm getter và setter (còn được gọi là bộ truy cập và bộ biến đổi) nên được sử dụng khi chúng cung cấp vai trò hoặc hành vi có ý nghĩa để nhận hoặc đặt giá trị của biến Đặc biệt, chúng nên được sử dụng khi nhận hoặc thiết lập biến phức tạp hoặc chi phí đáng kể, hiện tại hoặc trong tương lai hợp lý Ví dụ: nếu một cặp getters/setters chỉ đọc và ghi một thuộc tính nội bộ, thì thuộc tính nội bộ sẽ được công khai thay thế. Để so sánh, nếu việc đặt một biến có nghĩa là một số trạng thái bị vô hiệu hóa hoặc được xây dựng lại, thì đó phải là một hàm setter. Lời gọi hàm gợi ý rằng một hoạt động có khả năng không tầm thường đang xảy ra. Ngoài ra, có thể là một tùy chọn khi cần logic đơn giản hoặc tái cấu trúc để không còn cần getters và setters nữa Getters và setters nên tuân theo các hướng dẫn, chẳng hạn như 31 và 32Nếu hành vi trong quá khứ cho phép truy cập thông qua một thuộc tính, không liên kết các hàm getter/setter mới với thuộc tính. Bất kỳ mã nào vẫn đang cố truy cập vào biến theo phương pháp cũ sẽ bị hỏng rõ ràng để chúng nhận thức được sự thay đổi về độ phức tạp 3. 16 đặt tên 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45Tên hàm, tên biến và tên tệp phải mang tính mô tả; . Đặc biệt, không sử dụng các từ viết tắt mơ hồ hoặc không quen thuộc với người đọc bên ngoài dự án của bạn và không viết tắt bằng cách xóa các chữ cái trong một từ Luôn sử dụng phần mở rộng tên tệp 67. Không bao giờ sử dụng dấu gạch ngang3. 16. 1 Tên cần tránh
3. 16. 2 Quy ước đặt tên
3. 16. 3 Đặt tên tệpTên tệp Python phải có phần mở rộng 67 và không được chứa dấu gạch ngang ( 55). Điều này cho phép chúng được nhập và kiểm tra. Nếu bạn muốn một tệp thực thi có thể truy cập được mà không cần tiện ích mở rộng, hãy sử dụng liên kết tượng trưng hoặc trình bao bọc bash đơn giản có chứa 723. 16. 4 Nguyên tắc rút ra từ Khuyến nghị của GuidoTypePublicInternalPackages 73Modules 73 75Classes 76 77Exceptions 76Functions 79 80Global/Class Constants 81 82Global/Class Variables 73 75Instance Variables 73 75 (protected)Method Names 79 80 (protected)Function/Method Parameters 73Local Variables 733. 16. 5 Ký hiệu toán họcFor mathematically heavy code, short variable names that would otherwise violate the style guide are preferred when they match established notation in a reference paper or algorithm. Khi làm như vậy, hãy tham khảo nguồn của tất cả các quy ước đặt tên trong một nhận xét hoặc chuỗi tài liệu hoặc, nếu nguồn không thể truy cập được, hãy ghi lại rõ ràng các quy ước đặt tên. Ưu tiên 91 tuân thủ PEP8 cho các API công khai, có nhiều khả năng gặp phải ngoài ngữ cảnh hơn3. 17 MainIn Python, 25 as well as unit tests require modules to be importable. If a file is meant to be used as an executable, its main functionality should be in a 93 function, and your code should always check 94 before executing your main program, so that it is not executed when the module is importedWhen using absl, use 95 0Otherwise, use 1All code at the top level will be executed when the module is imported. Be careful not to call functions, create objects, or perform other operations that should not be executed when the file is being 25ed3. 18 Function lengthPrefer small and focused functions We recognize that long functions are sometimes appropriate, so no hard limit is placed on function length. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code You could find long and complicated functions when working with some code. Do not be intimidated by modifying existing code. if working with such a function proves to be difficult, you find that errors are hard to debug, or you want to use a piece of it in several different contexts, consider breaking up the function into smaller and more manageable pieces 3. 19 Type Annotations3. 19. 1 General Rules
3. 19. 2 Line BreakingTry to follow the existing rules After annotating, many function signatures will become “one parameter per line”. To ensure the return type is also given its own line, a comma can be placed after the last parameter 3Always prefer breaking between variables, and not, for example, between variable names and type annotations. However, if everything fits on the same line, go for it 4If the combination of the function name, the last parameter, and the return type is too long, indent by 4 in a new line. When using line breaks, prefer putting each parameter and the return type on their own lines and aligning the closing parenthesis with the 50 5Optionally, the return type may be put on the same line as the last parameter 6 18 allows you to move the closing parenthesis to a new line and align with the opening one, but this is less readable 7As in the examples above, prefer not to break types. However, sometimes they are too long to be on a single line (try to keep sub-types unbroken) 8If a single name and type is too long, consider using an for the type. The last resort is to break after the colon and indent by 4 9 03. 19. 3 Forward DeclarationsIf you need to use a class name (from the same module) that is not yet defined – for example, if you need the class name inside the declaration of that class, or if you use a class that is defined later in the code – either use 04 or use a string for the class name 1 23. 19. 4 Default ValuesAs per , use spaces around the 51 only for arguments that have both a type annotation and a default value 3 43. 19. 5 NoneTypeTrong hệ thống kiểu Python, 06 là kiểu "hạng nhất" và vì mục đích đánh máy, 98 là bí danh của 06. If an argument can be 98, it has to be declared. You can use 10, but if there is only one other type, use 11Use explicit 11 instead of implicit 11. Earlier versions of PEP 484 allowed 14 to be interpreted as 15, but that is no longer the preferred behavior 5 63. 19. 6 Type AliasesYou can declare aliases of complex types. The name of an alias should be CapWorded. If the alias is used only in this module, it should be _Private For example, if the name of the module together with the name of the type is too long 7Other examples are complex nested types and multiple return variables from a function (as a tuple) 3. 19. 7 Ignoring TypesYou can disable type checking on a line with the special comment 16 17 has a disable option for specific errors (similar to lint) 83. 19. 8 Typing VariablesIf an internal variable has a type that is hard or impossible to infer, specify its type with an annotated assignment - use a colon and type between the variable name and value (the same as is done with function arguments that have a default value) 9Though you may see them remaining in the codebase (they were necessary before Python 3. 6), do not add any more uses of a 18 comment on the end of the line 003. 19. 9 Tuples vs ListsTyped lists can only contain objects of a single type. Typed tuples can either have a single repeated type or a set number of elements with different types. The latter is commonly used as the return type from a function 013. 19. 10 TypeVarsThe Python type system has . The factory function 55 is a common way to use themExample 02A TypeVar can be constrained 03A common predefined type variable in the 21 module is 21. Use it for multiple annotations that can be 22 or 23 and must all be the same type 04A TypeVar must have a descriptive name, unless it meets all of the following criteria
05 063. 19. 11 String types
Use 23 for string/text data. For code that deals with binary data, use 22 07If all the string types of a function are always the same, for example if the return type is the same as the argument type in the code above, use 3. 19. 12 Imports For TypingFor symbols from the 21 and 22 modules used to support static analysis and type checking, always import the symbol itself. Điều này giữ cho các chú thích phổ biến ngắn gọn hơn và phù hợp với các cách gõ được sử dụng trên khắp thế giới. Bạn rõ ràng được phép nhập nhiều lớp cụ thể trên một dòng từ các mô-đun 21 và 22. Bán tại 08Cho rằng cách nhập này thêm các mục vào không gian tên cục bộ, các tên trong 21 hoặc 22 phải được xử lý tương tự như các từ khóa và không được xác định trong mã Python của bạn, được nhập hay không. Nếu có xung đột giữa một loại và một tên hiện có trong một mô-đun, hãy nhập nó bằng cách sử dụng 33 09Ưu tiên sử dụng các loại tích hợp làm chú thích nếu có. Python hỗ trợ các chú thích loại bằng cách sử dụng các loại vùng chứa tham số qua PEP-585, được giới thiệu trong Python 3. 9 10NOTE. Người dùng Apache Beam nên tiếp tục nhập vùng chứa tham số từ 21 113. 19. 13 Nhập khẩu có điều kiệnChỉ sử dụng nhập có điều kiện trong các trường hợp đặc biệt khi phải tránh nhập bổ sung cần thiết để kiểm tra loại trong thời gian chạy. Mô hình này không được khuyến khích; Imports that are needed only for type annotations can be placed within an 35 block
3. 19. 14 Circular DependenciesCircular dependencies that are caused by typing are code smells. Such code is a good candidate for refactoring. Although technically it is possible to keep circular dependencies, various build systems will not let you do so because each module has to depend on the other Replace modules that create circular dependency imports with 01. Set an with a meaningful name, and use the real type name from this module (any attribute of Any is Any). Alias definitions should be separated from the last import by one line 133. 19. 15 GenericsWhen annotating, prefer to specify type parameters for generic types; otherwise, 14 15If the best type parameter for a generic is 01, make it explicit, but remember that in many cases might be more appropriate 16 174 Parting WordsBE CONSISTENT If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this What is the best style guide for Python?Python has an excellent style guide called PEP8 . It covers most of the situations you will step into while writing Python. I like PEP8, I believe there has been much effort and thinking put into it.
How can I improve my Python coding style?Consider these Python best practices when Python Coding. . Follow the PEP 8 Style Guide for Python Code. . Use Python 3 Instead of Python 2. . Check for the Minimum Required Python Version. . Use the PyPI Instead of Doing It Yourself. . Document and Comment Your Code Properly. . Fix Code Issues Promptly. . Write Readable Code What is proper code formatting Python?There should be two blank lines surrounding classes and top-level functions . The methods inside of the class should be surrounded by a single blank line only. The preferred method of indentation is spaces, the 4 spaces indentation is accepted and accurate, but still, most people prefer tab indentation.
Cách thụt đầu dòng thực hành tốt nhất trong Python là gì?Indentation. You should use four spaces per indentation level . Spaces, and not tabs, are the preferred indentation method in Python. |