Thư viện python kỳ lạ
Những người đồng sáng lập DataCamp, Jonathan Cornelissen và Martijn Theuwissen phân tích các xu hướng dữ liệu hàng đầu mà họ đang thấy trong không gian dữ liệu ngày nay, cũng như dự đoán của họ về tương lai của ngành dữ liệu Show
Python là ngôn ngữ động chính được sử dụng tại Google. Hướng dẫn về phong cách này là danh sách những điều nên làm và không nên làm đối với các chương trình Python Để giúp bạn định dạng mã chính xác, chúng tôi đã tạo tệp cài đặt cho Vim. Đối với Emacs, cài đặt mặc định sẽ ổn Nhiều nhóm sử dụng trình định dạng tự động yapf để tránh tranh cãi về định dạng 2 Quy tắc ngôn ngữ Python2. 1 xơ vảiChạy 18 trên mã của bạn bằng cách sử dụng pylintrc này2. 1. 1 Định nghĩa 18 là một công cụ để tìm lỗi và các vấn đề về kiểu dáng trong mã nguồn Python. Nó tìm thấy các vấn đề thường được trình biên dịch bắt gặp đối với các ngôn ngữ kém năng động hơn như C và C++. Do tính chất động của Python, một số cảnh báo có thể không chính xác; 2. 1. 2 Ưu điểmBắt các lỗi dễ bỏ sót như lỗi chính tả, sử dụng-vars-trước khi gán, v.v. 2. 1. 3 nhược điểm 18 không hoàn hảo. Để tận dụng lợi thế của nó, đôi khi chúng ta cần phải viết xung quanh nó, loại bỏ các cảnh báo của nó hoặc sửa chữa nó2. 1. 4 Quyết địnhHãy chắc chắn rằng bạn chạy 18 trên mã của bạnLoại bỏ các cảnh báo nếu chúng không phù hợp để các vấn đề khác không bị ẩn. Để chặn cảnh báo, bạn có thể đặt nhận xét cấp dòng
18 cảnh báo, mỗi cảnh báo được xác định bằng tên tượng trưng ( 23) Cảnh báo dành riêng cho Google bắt đầu bằng 24Nếu lý do ngăn chặn không rõ ràng từ tên biểu tượng, hãy thêm một lời giải thích Loại bỏ theo cách này có lợi thế là chúng ta có thể dễ dàng tìm kiếm các loại bỏ và xem lại chúng Bạn có thể nhận danh sách 18 cảnh báo bằng cách thực hiệnĐể có thêm thông tin về một tin nhắn cụ thể, hãy sử dụng Thích 26 hơn mẫu cũ hơn không dùng nữa 27Có thể loại bỏ các cảnh báo đối số không sử dụng bằng cách xóa các biến ở đầu hàm. Luôn bao gồm một bình luận giải thích lý do tại sao bạn xóa nó. “Không sử dụng. " là đủ. Ví dụ
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 Định nghĩaCơ chế tái sử dụng để chia sẻ mã từ mô-đun này sang mô-đun khác 2. 2. 2 Ưu điểmQuy ước quản lý không gian tên rất đơn giản. Nguồn của mỗi mã định danh được chỉ định một cách nhất quán; 2. 2. 3 nhược điểmTên mô-đun vẫn có thể xung đột. Một số tên mô-đun dài bất tiện 2. 2. 4 Quyết định
Ví dụ: mô-đun 47 có thể được nhập như sau
Không sử dụng tên họ hàng trong nhập khẩu. Ngay cả khi mô-đun nằm trong cùng một gói, hãy sử dụng tên gói đầy đủ. Điều này giúp ngăn việc vô tình nhập một gói hai lần 2. 2. 4. 1 miễn trừMiễn trừ từ quy tắc này
2. 3 góiNhập từng mô-đun bằng vị trí tên đường dẫn đầy đủ của mô-đun 2. 3. 1 Ưu điểmTránh xung đột về tên mô-đun hoặc nhập sai do đường dẫn tìm kiếm mô-đun không như tác giả mong đợi. Giúp tìm kiếm các mô-đun dễ dàng hơn 2. 3. 2 nhược điểmLàm cho việc triển khai mã trở nên khó khăn hơn vì bạn phải sao chép hệ thống phân cấp gói. Không thực sự là một vấn đề với các cơ chế triển khai hiện đại 2. 3. 3 Quyết địnhTất cả mã mới phải nhập từng mô-đun theo tên gói đầy đủ của nó Nhập khẩu phải như sau
(giả sử tệp này tồn tại ở 48 nơi mà 49 cũng tồn tại)
Thư mục chứa tệp nhị phân chính không nên được coi là ở trong 50 mặc dù điều đó xảy ra trong một số môi trường. Trong trường hợp này, mã phải giả định rằng 51 đề cập đến bên thứ ba hoặc gói cấp cao nhất có tên là 52, không phải là địa phương 492. 4 ngoại lệNgoại lệ được cho phép nhưng phải được sử dụng cẩn thận 2. 4. 1 Định nghĩaNgoại lệ là phương tiện thoát ra khỏi luồng điều khiển thông thường để xử lý lỗi hoặc các điều kiện ngoại lệ khác 2. 4. 2 Ưu điểmLuồng điều khiển của mã hoạt động bình thường không bị lộn xộn bởi mã xử lý lỗi. Nó cũng cho phép luồng điều khiển bỏ qua nhiều khung khi một điều kiện nhất định xảy ra, e. g. , quay lại từ N hàm lồng nhau trong một bước thay vì phải tìm mã lỗi thông qua 2. 4. 3 nhược điểmCó thể khiến luồng điều khiển bị nhầm lẫn. Dễ bỏ sót các trường hợp lỗi khi gọi thư viện 2. 4. 4 Quyết địnhNgoại lệ phải tuân theo các điều kiện nhất định
2. 5 trạng thái toàn cầu có thể thay đổiTránh trạng thái toàn cầu có thể thay đổi 2. 5. 1 Định nghĩaCác giá trị cấp mô-đun hoặc thuộc tính lớp có thể bị thay đổi trong quá trình thực thi chương trình 2. 5. 2 Ưu điểmThỉnh thoảng hữu ích 2. 5. 3 nhược điểm
2. 5. 4 Quyết địnhTránh trạng thái toàn cầu có thể thay đổi 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 trongCác hàm hoặc lớp cục bộ lồng nhau vẫn ổn khi được sử dụng để đóng trên một biến cục bộ. Các lớp bên trong vẫn ổn 2. 6. 1 Định nghĩaMột lớp có thể được định nghĩa bên trong một phương thức, hàm hoặc lớp. Một hàm có thể được định nghĩa bên trong một phương thức hoặc hàm. Các hàm lồng nhau có quyền truy cập chỉ đọc vào các biến được xác định trong phạm vi kèm theo 2. 6. 2 Ưu điểmCho phép định nghĩa các lớp và chức năng tiện ích chỉ được sử dụng bên trong phạm vi rất hạn chế. Rất ADT-y. Thường được sử dụng để thực hiện trang trí 2. 6. 3 nhược điểmCác hàm và lớp lồng nhau không thể được kiểm tra trực tiếp. Việc lồng nhau có thể làm cho chức năng bên ngoài dài hơn và khó đọc hơn 2. 6. 4 Quyết địnhHọ ổn với một số lưu ý. Tránh các hàm hoặc lớp lồng nhau trừ khi đóng trên một giá trị cục bộ khác với 73 hoặc 74. Không lồng chức năng chỉ để ẩn nó khỏi người dùng mô-đun. Thay vào đó, hãy đặt tiền tố tên của nó bằng _ ở cấp độ mô-đun để nó vẫn có thể được truy cập bằng các thử nghiệm2. 7 cách hiểu và biểu thức trình tạoĐược rồi để sử dụng cho các trường hợp đơn giản 2. 7. 1 Định nghĩaKhả năng hiểu List, Dict và Set cũng như các biểu thức trình tạo cung cấp một cách ngắn gọn và hiệu quả để tạo các loại bộ chứa và bộ lặp mà không cần sử dụng các vòng lặp truyền thống, 75, 76 hoặc 772. 7. 2 Ưu điểmViệ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 dẹp 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ểmNgắn gọn và thuận tiện hơn câu lệnh if 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. Các giá trị đối số mặc định cung cấp một cách dễ dàng để thực hiện việc này mà không cần phải xác định nhiều hàm cho các trường hợp ngoại lệ hiếm gặp. Vì Python không hỗ trợ các phương thức/hàm quá tải, nên các đối số mặc định là một cách dễ dàng để “làm giả” hành vi quá tải 2. 12. 3 nhược điểmCá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. , bằng cách thêm một mục vào danh sách), giá trị mặc định được sửa đổi 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 Lexical ScopingOkay to use 2. 16. 1 DefinitionA nested Python function can refer to variables defined in enclosing functions, but cannot assign to them. Variable bindings are resolved using lexical scoping, that is, based on the static program text. Any assignment to a name in a block will cause Python to treat all references to that name as a local variable, even if the use precedes the assignment. If a global declaration occurs, the name is treated as a global variable An example of the use of this feature is 82. 16. 2 ProsOften results in clearer, more elegant code. Especially comforting to experienced Lisp and Scheme (and Haskell and ML and …) programmers 2. 16. 3 ConsCan lead to confusing bugs. Such as this example based on PEP-0227 9Vì vậy, 17 sẽ in ra 18, không phải là 192. 16. 4 Quyết địnhOkay to use 2. 17 Trình trang trí chức năng và phương phápSử 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 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 ánh (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 địnhYou are strongly encouraged to enable Python type analysis when updating code. 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 đó, các 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ã nếu phù 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 Line lengthĐộ 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. If necessary, you can add an extra pair of parentheses around an expression 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 0Make note of the indentation of the elements in the line continuation examples above; see the section for explanation In all other cases where a line exceeds 80 characters, and the yapf auto-formatter does not help bring the line below the limit, the line is allowed to exceed this maximum. Authors are encouraged to manually break the line up per the notes above when it is sensible 3. 3 ParenthesesUse parentheses sparingly It is fine, though not required, to use parentheses around tuples. Do not use them in return statements or conditional statements unless using parentheses for implied line continuation or to indicate a tuple 1 23. 4 IndentationIndent your code blocks with 4 spaces Never use tabs. Implied line continuation should align wrapped elements vertically (see ), or use a hanging 4-space indent. Closing (round, square or curly) brackets can be placed at the end of the expression, or on separate lines, but then should be indented the same as the line with the corresponding opening bracket 3 43. 4. 1 Trailing commas in sequences of items?Trailing commas in sequences of items are recommended only when the closing container token 45, 46, or 47 does not appear on the same line as the final element. The presence of a trailing comma is also used as a hint to our Python code auto-formatter YAPF to direct it to auto-format the container of items to one item per line when the 48 after the final element is present 53. 5 Blank LinesTwo blank lines between top-level definitions, be they function or class definitions. One blank line between method definitions and between the docstring of a 49 and the first method. No blank line following a 50 line. Use single blank lines as you judge appropriate within functions or methodsBlank lines need not be anchored to the definition. For example, related comments immediately preceding function, class, and method definitions can make sense. Consider if your comment might be more useful as part of the docstring 3. 6 WhitespaceFollow standard typographic rules for the use of spaces around punctuation No whitespace inside parentheses, brackets or braces 6 7No whitespace before a comma, semicolon, or colon. Do use whitespace after a comma, semicolon, or colon, except at the end of the line 8 9No whitespace before the open paren/bracket that starts an argument list, indexing or slicing 0 1No trailing whitespace 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). Use your better judgment for the insertion of spaces around arithmetic operators ( 54, 55, 56, 57, 58, 59, 60, 22)Never use spaces around 51 when passing keyword arguments or defining a default parameter value, with one exception. , do use spaces around the 51 for the default parameter value 2 3Don’t use spaces to vertically align tokens on consecutive lines, since it becomes a maintenance burden (applies to 64, 65, 51, etc. ) 4 53. 7 Shebang LineMost 67 files do not need to start with a 68 line. Start the main file of a program with 69 (to support virtualenvs) or 70 per PEP-394This line is used by the kernel to find the Python interpreter, but is ignored by Python when importing modules. It is only necessary on a file intended to be executed directly Be sure to use the right style for module, function, method docstrings and inline comments 3. 8. 1 DocstringsPython uses docstrings to document code. A docstring is a string that is the first statement in a package, module, class or function. These strings can be extracted automatically through the 71 member of the object and are used by 25. (Try running 25 on your module to see how it looks. ) Always use the three double-quote 74 format for docstrings (per PEP 257). A docstring should be organized as a summary line (one physical line not exceeding 80 characters) terminated by a period, question mark, or exclamation point. When writing more (encouraged), this must be followed by a blank line, followed by the rest of the docstring starting at the same cursor position as the first quote of the first line. There are more formatting guidelines for docstrings below3. 8. 2 ModulesEvery file should contain license boilerplate. Choose the appropriate boilerplate for the license used by the project (for example, Apache 2. 0, BSD, LGPL, GPL) Files should start with a docstring describing the contents and usage of the module 63. 8. 2. 1 Test modulesModule-level docstrings for test files are not required. They should be included only when there is additional information that can be provided Examples include some specifics on how the test should be run, an explanation of an unusual setup pattern, dependency on the external environment, and so on 7Docstrings that do not provide any new information should not be used 3. 8. 3 Functions and MethodsIn this section, “function” means a method, function, generator, or property A docstring is mandatory for every function that has one or more of the following properties
A docstring should give enough information to write a call to the function without reading the function’s code. The docstring should describe the function’s calling syntax and its semantics, but generally not its implementation details, unless those details are relevant to how the function is to be used. For example, a function that mutates one of its arguments as a side effect should note that in its docstring. Otherwise, subtle but important details of a function’s implementation that are not relevant to the caller are better expressed as comments alongside the code than within the function’s docstring The docstring may be descriptive-style ( 75) or imperative-style ( 76), but the style should be consistent within a file. The docstring for a 91 data descriptor should use the same style as the docstring for an attribute or a ( 78, rather than 79)A method that overrides a method from a base class may have a simple docstring sending the reader to its overridden method’s docstring, such as 80. The rationale is that there is no need to repeat in many places documentation that is already present in the base method’s docstring. However, if the overriding method’s behavior is substantially different from the overridden method, or details need to be provided (e. g. , documenting additional side effects), a docstring with at least those differences is required on the overriding methodCertain aspects of a function should be documented in special sections, listed below. Each section begins with a heading line, which ends with a colon. All sections other than the heading should maintain a hanging indent of two or four spaces (be consistent within a file). These sections can be omitted in cases where the function’s name and signature are informative enough that it can be aptly described using a one-line docstring List each parameter by name. A description should follow the name, and be separated by a colon followed by either a space or newline. If the description is too long to fit on a single 80-character line, use a hanging indent of 2 or 4 spaces more than the parameter name (be consistent with the rest of the docstrings in the file). The description should include required type(s) if the code does not contain a corresponding type annotation. If a function accepts 81 (variable length argument lists) and/or 82 (arbitrary keyword arguments), they should be listed as 81 and 82. Describe the type and semantics of the return value. If the function only returns None, this section is not required. It may also be omitted if the docstring starts with Returns or Yields (e. g. 85) and the opening sentence is sufficient to describe the return value. Do not imitate ‘NumPy style’ (example), which frequently documents a tuple return value as if it were multiple return values with individual names (never mentioning the tuple). Instead, describe such a return value as. “Returns. A tuple (mat_a, mat_b), where mat_a is …, and …”. The auxiliary names in the docstring need not necessarily correspond to any internal names used in the function body (as those are not part of the API). List all exceptions that are relevant to the interface followed by a description. Use a similar exception name + colon + space or newline and hanging indent style as described in Args. You should not document exceptions that get raised if the API specified in the docstring is violated (because this would paradoxically make behavior under violation of the API part of the 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 ClassesClasses should have a docstring below the class definition describing the class. If your class has public attributes, they should be documented here in an 87 section and follow the same formatting as a section 0All class docstrings should start with a one-line summary that describes what the class instance represents. This implies that subclasses of 60 should also describe what the exception represents, and not the context in which it might occur. The class docstring should not repeat unnecessary information, such as that the class is a class 1 23. 8. 5 Block and Inline CommentsNơi cuối cùng để có nhận xét là ở những phần phức tạp của mã. If you’re going to have to explain it at the next code review, you should comment it now. 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 dấu cách 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 được 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 thực hành 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ế. By comparison, if setting a variable means some state is invalidated or rebuilt, it should be a setter function. 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ệpPython filenames must have a 67 extension and must not contain dashes ( 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ọcĐối với mã nặng về mặt toán học, các tên biến ngắn sẽ vi phạm hướng dẫn kiểu được ưu tiên hơn khi chúng khớp với ký hiệu đã thiết lập trong tài liệu tham khảo hoặc thuật toán. 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 chínhTrong Python, 25 cũng như các bài kiểm tra đơn vị yêu cầu các mô-đun có thể nhập được. Nếu một tệp được dùng làm tệp thực thi, thì chức năng chính của nó phải ở hàm 93 và mã của bạn phải luôn kiểm tra 94 trước khi thực thi chương trình chính của bạn, để nó không được thực thi khi mô-đun được nhậpKhi sử dụng absl, hãy sử dụng 95 0Nếu không, hãy sử dụng 1Tất cả mã ở cấp cao nhất sẽ được thực thi khi mô-đun được nhập. Cẩn thận không gọi hàm, tạo đối tượng hoặc thực hiện các thao tác khác không được thực hiện khi tệp đang được ____32_______25ed 3. 18 Chiều dài chức năngThích các chức năng nhỏ và tập trung Chúng tôi nhận ra rằng các hàm dài đôi khi phù hợp, vì vậy không có giới hạn cứng nào được đặt cho độ dài của hàm. Nếu một hàm vượt quá khoảng 40 dòng, hãy nghĩ xem có thể chia nhỏ hàm đó mà không làm hại cấu trúc của chương trình hay không Ngay cả khi chức năng lâu dài của bạn hiện đang hoạt động hoàn hảo, ai đó sửa đổi nó sau vài tháng có thể thêm hành vi mới. Điều này có thể dẫn đến các lỗi khó tìm. Giữ chức năng của bạn ngắn gọn và đơn giản giúp người khác đọc và sửa đổi mã của bạn dễ dàng hơn Bạn có thể tìm thấy các hàm dài và phức tạp khi làm việc với một số mã. Đừng bị đe dọa bằng cách sửa đổi mã hiện có. nếu làm việc với một chức năng như vậy tỏ ra khó khăn, bạn thấy rằng các lỗi khó gỡ lỗi hoặc bạn muốn sử dụng một phần của nó trong nhiều ngữ cảnh khác nhau, hãy cân nhắc chia chức năng thành các phần nhỏ hơn và dễ quản lý hơn 3. 19 Chú thích Loại3. 19. 1 Quy tắc chung
3. 19. Ngắt 2 dòngCố gắng tuân theo các quy tắc hiện có Sau khi chú thích, nhiều chữ ký hàm sẽ trở thành “mỗi dòng một tham số”. Để đảm bảo kiểu trả về cũng được cung cấp dòng riêng, có thể đặt dấu phẩy sau tham số cuối cùng 3Luôn ưu tiên ngắt giữa các biến và không, ví dụ, giữa tên biến và chú thích loại. Tuy nhiên, nếu mọi thứ phù hợp trên cùng một dòng, hãy tiếp tục 4Nếu tổ hợp tên hàm, tham số cuối cùng và kiểu trả về quá dài, hãy thụt lề 4 trong một dòng mới. Khi sử dụng ngắt dòng, hãy ưu tiên đặt từng tham số và kiểu trả về trên các dòng riêng của chúng và căn chỉnh dấu ngoặc đơn đóng với 50 5Tùy chọn, kiểu trả về có thể được đặt trên cùng một dòng với tham số cuối cùng 6 18 cho phép bạn di chuyển dấu ngoặc đơn đóng sang một dòng mới và căn chỉnh với dòng mở đầu, nhưng điều này khó đọc hơn 7Như trong các ví dụ trên, không muốn ngắt các loại. Tuy nhiên, đôi khi chúng quá dài để nằm trên một dòng (cố gắng giữ cho các loại phụ không bị gián đoạn) 8Nếu một tên và loại quá dài, hãy xem xét sử dụng một loại cho. Phương án cuối cùng là ngắt sau dấu hai chấm và thụt vào 4 9 03. 19. 3 Tuyên bố chuyển tiếpNếu bạn cần sử dụng một tên lớp (từ cùng một mô-đun) chưa được xác định – ví dụ: nếu bạn cần tên lớp bên trong phần khai báo của lớp đó hoặc nếu bạn sử dụng một lớp được xác định sau trong mã – 1 23. 19. 4 giá trị mặc địnhTheo , chỉ sử dụng khoảng trắng xung quanh 51 cho các đối số có cả chú thích loại và giá trị mặc định 3 43. 19. 5 Không có LoạiTrong 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. Nếu một đối số có thể là 98, thì nó phải được khai báo. Bạn có thể sử dụng 10, nhưng nếu chỉ có một loại khác, hãy sử dụng 11Sử dụng 11 rõ ràng thay vì ngầm ẩn 11. Các phiên bản trước của PEP 484 cho phép 14 được hiểu là 15, nhưng đó không còn là hành vi được ưu tiên nữa 5 63. 19. 6 bí danh loạiBạn có thể khai báo bí danh của các loại phức tạp. Tên của bí danh phải là CapWorded. Nếu bí danh chỉ được sử dụng trong mô-đun này, thì bí danh đó phải là _Private Ví dụ: nếu tên của mô-đun cùng với tên của loại quá dài 7Các ví dụ khác là các kiểu lồng nhau phức tạp và nhiều biến trả về từ một hàm (dưới dạng một bộ) 3. 19. 7 kiểu phớt lờBạn có thể tắt kiểm tra loại trên một dòng bằng chú thích đặc biệt 16 17 có tùy chọn tắt đối với các lỗi cụ thể (tương tự như xơ vải) 83. 19. 8 biến gõNếu một biến nội bộ có loại khó hoặc không thể suy luận, hãy chỉ định loại của biến đó bằng cách gán có chú thích - sử dụng dấu hai chấm và nhập giữa tên và giá trị biến (tương tự như được thực hiện với các đối số hàm có giá trị mặc định) 9Mặc dù bạn có thể thấy chúng còn lại trong cơ sở mã (chúng cần thiết trước Python 3. 6), không thêm bất kỳ cách sử dụng nào nữa của nhận xét 18 ở cuối dòng 003. 19. 9 Tuples vs Danh sáchDanh sách đã nhập chỉ có thể chứa các đối tượng thuộc một loại. Các bộ dữ liệu đã nhập có thể có một loại lặp lại duy nhất hoặc một số phần tử được đặt với các loại khác nhau. Cái sau thường được sử dụng làm kiểu trả về từ một hàm 013. 19. 10 LoạiVarsHệ thống kiểu Python có. Chức năng nhà máy 55 là một cách phổ biến để sử dụng chúngThí dụ 02Một TypeVar có thể bị ràng buộc 03Biến loại được xác định trước phổ biến trong mô-đun 21 là 21. Sử dụng nó cho nhiều chú thích có thể là 22 hoặc 23 và tất cả phải cùng loại 04TypeVar phải có tên mô tả, trừ khi nó đáp ứng tất cả các tiêu chí sau
05 063. 19. 11 loại chuỗi
Sử dụng 23 cho dữ liệu chuỗi/văn bản. Đối với mã liên quan đến dữ liệu nhị phân, hãy sử dụng 22 07Nếu tất cả các kiểu chuỗi của một hàm luôn giống nhau, chẳng hạn nếu kiểu trả về giống với kiểu đối số trong đoạn mã trên, hãy sử dụng 3. 19. 12 Nhập khẩu để gõĐối với các ký hiệu từ các mô-đun 21 và 22 được sử dụng để hỗ trợ phân tích tĩnh và kiểm tra loại, hãy luôn nhập chính ký hiệu đó. Đ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ó sự 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 10GHI CHÚ. 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; Các mục nhập chỉ cần thiết cho chú thích loại có thể được đặt trong một khối 35
3. 19. 14 phụ thuộc tuần hoànCác phụ thuộc tròn gây ra bởi việc gõ là mã có mùi. Mã như vậy là một ứng cử viên tốt để tái cấu trúc. Mặc dù về mặt kỹ thuật, có thể giữ các phụ thuộc vòng tròn, nhưng các hệ thống xây dựng khác nhau sẽ không cho phép bạn làm như vậy vì mỗi mô-đun phải phụ thuộc vào mô-đun khác Thay thế các mô-đun tạo nhập khẩu phụ thuộc vòng tròn bằng 01. Đặt một tên có ý nghĩa và sử dụng tên loại thực từ mô-đun này (bất kỳ thuộc tính nào của Any là Any). Các định nghĩa bí danh phải được phân tách khỏi lần nhập cuối cùng bằng một dòng 133. 19. 15 thuốc gốcKhi chú thích, ưu tiên chỉ định tham số loại cho các loại chung; 14 15Nếu tham số loại tốt nhất cho một tên chung là 01, hãy làm cho nó rõ ràng, nhưng hãy nhớ rằng trong nhiều trường hợp có thể phù hợp hơn 16 174 Lời Chia TayHÃY KIÊN NHẪN Nếu bạn đang chỉnh sửa mã, hãy dành vài phút để xem mã xung quanh bạn và xác định phong cách của nó. Nếu họ sử dụng khoảng trắng xung quanh tất cả các toán tử số học của họ, thì bạn cũng nên. Nếu nhận xét của họ có các hộp dấu thăng nhỏ xung quanh, hãy làm cho nhận xét của bạn cũng có các hộp dấu thăng nhỏ xung quanh chúng Mục đích của việc có các hướng dẫn về phong cách là có một vốn từ vựng chung về viết mã để mọi người có thể tập trung vào những gì bạn đang nói hơn là vào cách bạn nói. Chúng tôi trình bày các quy tắc phong cách toàn cầu ở đây để mọi người biết từ vựng, nhưng phong cách địa phương cũng rất quan trọng. Nếu mã bạn thêm vào một tệp trông khác hẳn so với mã hiện có xung quanh nó, nó sẽ khiến người đọc mất nhịp khi họ đọc nó. Tránh điều này |