Hướng dẫn python google docstring - python google docstring
Hướng dẫn theo phong cách Google PythonMục lục
1. Bối cảnhPython là ngôn ngữ động chính được sử dụng tại Google. Hướng dẫn phong cách này là một danh sách các DOS và don lồng cho các chương trình Python. Show
Để giúp bạn định dạng mã chính xác, chúng tôi đã tạo một tệp cài đặt cho VIM. Đối với Emacs, cài đặt mặc định sẽ ổn. Nhiều đội sử dụng nhân vật tự động YAPF để tránh tranh luận về định dạng. 2 Quy tắc ngôn ngữ Python2.1 LintChạy 16 qua mã của bạn bằng pylintrc này.2.1.1 Định nghĩa 16 là một công cụ để tìm lỗi và các vấn đề về kiểu 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ữ ít động hơn như C và C ++. Do tính chất năng động của Python, một số cảnh báo có thể không chính xác; Tuy nhiên, cảnh báo giả nên khá không thường xuyên.2.1.2 Ưu điểmBắt các lỗi dễ nhớ như lỗi chính tả, sử dụng vars-do-gán, v.v. 2.1.3 Nhược điểm 16 là hoàn hảo. Để tận dụng lợi thế của nó, đôi khi chúng ta sẽ cần phải viết xung quanh nó, đàn áp cảnh báo của nó hoặc sửa nó.2.1.4 Quyết địnhHãy chắc chắn rằng bạn chạy 16 trên mã của bạn.Bị cảnh báo nếu chúng không phù hợp để các vấn đề khác không bị ẩn. Để ngăn chặn các cảnh báo, bạn có thể đặt một nhận xét cấp độ dòng:
Các cảnh báo 16 được xác định theo tên biểu tượng ( 21) Các cảnh báo cụ thể của Google bắt đầu với 22.Nếu lý do cho sự đàn áp không rõ ràng từ tên biểu tượng, hãy thêm một lời giải thích. Ức chế theo cách này có lợi thế là chúng ta có thể dễ dàng tìm kiếm các sự đàn áp và xem lại chúng. Bạn có thể nhận được một danh sách các cảnh báo 16 bằng cách thực hiện:Để có thêm thông tin về một thông báo cụ thể, hãy sử dụng: Thích 24 hơn mẫu cũ không dùng nữa 25.Các cảnh báo đối số không sử dụng có thể bị triệt tiêu 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 đang xóa nó. "Không được sử dụng." là đủ. Ví dụ:
Các hình thức phổ biến khác của việc đàn áp cảnh báo này bao gồm sử dụng ‘ 26, làm người định danh cho đối số không sử dụng hoặc tiền tố tên đối số với‘ 27, hoặc gán chúng cho ‘ 26. Những hình thức này được cho phép nhưng không còn được khuyến khích. Những người gọi phá vỡ này vượt qua các đối số theo tên và không thực thi rằng các đối số thực sự không được sử dụng.2.2 Nhập khẩuChỉ sử dụng các câu lệnh 29 cho các gói và mô -đun, không phải 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ểmHội nghị quản lý không gian tên là đơn giản. Nguồn của mỗi định danh được chỉ định một cách nhất quán; 30 nói rằng đối tượng 31 được xác định trong mô -đun 32.2.2.3 nhược điểmTên mô -đun vẫn có thể va chạm. Một số tên mô -đun dài bất tiện. 2.2.4 Quyết định
Ví dụ: mô -đun 45 có thể được nhập như sau:
Không sử dụng tên tương đối 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 chặn việc 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 mỗi mô -đun bằng cách sử dụng vị trí tên đường dẫn đầy đủ của mô -đun. 2.3.1 Ưu điểmTránh xung đột trong tên mô -đun hoặc nhập khẩu không chính xác do đường dẫn tìm kiếm mô -đun không phải là những gì tác giả mong đợi. Làm cho nó dễ dàng hơn để tìm các mô -đun. 2.3.2 Nhược điểmLàm cho khó khăn hơn để triển khai mã 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 sẽ nhập từng mô -đun bằng tên gói đầy đủ của nó. Nhập khẩu phải như sau:
(Giả sử tập tin này sống ở 49 trong đó 50 cũng tồn tại)
Thư mục nhị phân chính được đặt trong không nên được giả định là trong 51 mặc dù điều đó xảy ra trong một số môi trường. Đây là trường hợp, mã nên giả định rằng 52 đề cập đến gói thứ ba hoặc gói cấp cao nhất có tên 53, không phải là 50 cục bộ.2.4 ngoại lệCác trường hợp 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à một phương tiện để thoát ra khỏi luồng kiểm soát bình thường để xử lý các lỗi hoặc các điều kiện đặc biệt khác. 2.4.2 Ưu điểmDò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 hình khi một điều kiện nhất định xảy ra, ví dụ: trả lại từ các hàm N được lồng trong một bước thay vì phải thông qua các lỗi lỗi. 2.4.3 nhược điểmCó thể làm cho dòng điều khiển bị nhầm lẫn. Dễ dàng bỏ lỡ các trường hợp lỗi khi thực hiện cuộc 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 Biến toàn cầuTránh các biến toàn cầu. 2.5.1 Định nghĩaCác biến được khai báo ở cấp độ mô -đun hoặc là thuộc tính lớp. 2.5.2 Ưu điểmĐôi khi hữu ích. 2.5.3 nhược điểmCó khả năng thay đổi hành vi mô -đun trong quá trình nhập, bởi vì các bài tập cho các biến toàn cầu được thực hiện khi mô -đun được nhập lần đầu tiên. 2.5.4 Quyết địnhTránh các biến toàn cầu. 2.5.1 Định nghĩa Các biến được khai báo ở cấp độ mô -đun hoặc là thuộc tính lớp. 2.6 Các lớp và chức năng Nested/Local/InsideCác chức năng hoặc lớp cục bộ lồng nhau là tốt khi được sử dụng để đóng qua một biến cục bộ. Các lớp học bên trong là tốt. 2.6.1 Định nghĩaMột lớp có thể được xác định bên trong một phương thức, hàm hoặc lớp. Một hàm có thể được xác định bên trong một phương thức hoặc hàm. Các chức năng 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 chức năng và các lớp lồng nhau không thể được kiểm tra trực tiếp. Nesting có thể làm cho chức năng bên ngoài dài hơn và không thể đọc được. 2.6.4 Quyết địnhHọ ổn với một số cảnh báo. Tránh các hàm hoặc lớp lồng nhau trừ khi đóng qua giá trị cục bộ khác với 73 hoặc 74. Không tổ chức năng chỉ để ẩn nó khỏi người dùng của một mô -đun. Thay vào đó, tiền tố tên của nó với một _ ở cấp độ mô -đun để nó vẫn có thể được truy cập bằng các bài kiểm tra.2.7 Biểu thức toàn diện & 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ĩaDanh sách, Dict và đặt toàn bộ cũng như các biểu thức của máy phát cung cấp một cách ngắn gọn và hiệu quả để tạo các loại container và trình lặp mà không cần dùng đến việc sử dụng các vòng lặp truyền thống, 75, 76 hoặc 77.2.7.2 Ưu điểmCác toàn bộ đơn giản có thể rõ ràng và đơn giản hơn so với các Danh sách, danh sách hoặc thiết lập các kỹ thuật sáng tạo khác. Biểu thức của máy phát có thể rất hiệu quả, vì chúng tránh được việc tạo ra một danh sách hoàn toàn. 2.7.3 Nhược điểmChuỗi hiểu phức tạp hoặc biểu thức máy phát có thể khó đọc. 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 phù hợp với một dòng: Biểu thức ánh xạ, mệnh đề 78, Biểu thức bộ lọc. Không được phép cho phép các mệnh đề 78 hoặc biểu thức lọc. Sử dụng các vòng thay vì mọi thứ trở nên phức tạp hơn.
2.8 Máy lặp và toán tử mặc địnhSử dụng trình lặp mặc định và toán tử 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 container, như từ điển và danh sách, xác định các trình lặp lại mặc định và các toán tử kiểm tra thành viên (trên mạng và không phải trong phạm vi). 2.8.2 Ưu điểmCác phép lặp mặc định và toán tử là đơn giản và hiệu quả. Họ thể hiện hoạt động trực tiếp, mà không cần thêm các cuộc gọi phương thức. Một chức năng 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 hỗ trợ hoạt động. 2.8.3 Nhược điểmBạn có thể nói với 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 trình lặp mặc định và toán tử 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 xác định các phương thức lặp lại. Thích 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 biến đổi một thù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ĩaMột hàm Trình tạo trả về một trình lặp lại mang lại một giá trị mỗi khi nó thực thi một 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 máy phát được treo cho đến khi cần giá trị tiếp theo. 2.9.2 Ưu điểmMã đơn giản hơn, bởi vì trạng thái của các biến cục bộ và luồng điều khiển được bảo tồn cho mỗi cuộc gọi. Một trình tạo sử dụng ít bộ nhớ hơn một hàm tạo toàn bộ danh sách các giá trị cùng một lúc. 2.9.3 nhược điểmCác biến cục bộ trong máy phát sẽ không được thu gom rác cho đến khi máy phát điện được tiêu thụ đến kiệt sức hoặc chính nó được thu thập rác. 2.9.4 Quyết địnhKhỏe. Sử dụng năng suất của người dùng: Thay vì trả về của người khác: trong số các chức năng của DocString cho các chức năng của máy phát điện. Nếu máy phát quản lý một tài nguyên đắt tiền, hãy đảm bảo buộc phải dọn dẹp. Một cách tốt để làm sạch là bằng cách gói trình tạo bằng trình quản lý bối cảnh PEP-0533. 2.10 Chức năng LambdaĐược rồi cho một lớp lót. Thích biểu thức máy phát trên 75 hoặc 76 với 77.2.10.1 Định nghĩaLambdas xác định các hàm ẩn danh trong một biểu thức, trái ngược với một tuyên bố. 2.10.2 Ưu điểmConvenient. 2.10.3 Nhược điểmKhó đọc và gỡ lỗi hơn các chức năng địa phương. 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ì hàm 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 là định nghĩa nó là hàm lồng nhau 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 chức năng từ mô -đun 83 thay vì các hàm Lambda. Ví dụ, thích 84 đến 85.2.11 Biểu thức có điều kiệnĐược rồi cho những trường hợp đơn giản. 2.11.1 Định nghĩaCác biểu thức có điều kiện (đôi khi được gọi là toán tử ternary của người Hồi giáo) là các cơ chế cung cấp cú pháp ngắn hơn cho các câu lệnh IF. Ví dụ: 86.2.11.2 Ưu điểmNgắn hơn và thuận tiện hơn một câu lệnh if. 2.11.3 Nhược điểmCó thể khó đọc hơn một câu lệnh IF. Điều kiện có thể khó định vị 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 phù hợp với một dòng: biểu hiện đúng, biểu hiện if, biểu hiện khác. Sử dụng một tuyên bố 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 các giá trị cho các biến ở cuối danh sách tham số hàm, ví dụ: 87. Nếu 88 được gọi chỉ với một đối số, 89 sẽ được đặt thành 0. Nếu nó được gọi với hai đối số, 89 có giá trị của đối số thứ hai.2.12.2 Ưu điểmThông thường bạn có một hàm sử dụng nhiều giá trị mặc định, nhưng trong những trường hợp hiếm hoi, bạn muốn ghi đè các mặc định. Các giá trị đối số mặc định cung cấp một cách dễ dàng để làm điều này, mà không phải xác định nhiều chức năng cho các trường hợp ngoại lệ hiếm. Vì Python không hỗ trợ các phương thức/hàm bị quá tải, các đối số mặc định là một cách dễ dàng để giả mạo hành vi quá tải. 2.12.3 nhược điểmĐối số mặc định được đánh giá một lần tại thời gian tải mô -đun. Điều này có thể gây ra vấn đề nếu đối số là một đối tượng có thể thay đổi như danh sách hoặc từ điển. Nếu hàm sửa đổi đối tượng (ví dụ: bằng cách nối một mục vào danh sách), giá trị mặc định sẽ được sửa đổi. 2.12.4 Quyết địnhĐược rồi để sử dụng với những 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 tầm thường hoặc logic. Việc triển khai tài sản phải phù hợp với những kỳ vọng chung về quyền truy cập thuộc tính thông thường: rằng chúng rẻ, đơn giản và không có gì đáng ngạc nhiên. 2.13.1 Định nghĩaMột cách để bọc phương thức kêu gọi nhận và đặt mộ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 kỳ vọng của quyền truy cập thuộc tính điển hình; Thực hiện theo các quy tắc getters và setters khác. Ví dụ: sử dụng một thuộc tính để chỉ đơn giản là có được và đặt một thuộc tính nội bộ được phép: không có tính toán xảy ra, do đó, tài sản không cần thiết (thay vào đó, công khai thuộc tính). Để so sánh, 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 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 ra với bộ trang trí 91. Thực hiện thủ công một mô tả thuộc tính được coi là một tính năng năng lượng.Kế 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 các 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 các tính năng giả mạo của người Viking nếu có thể. 2.14.1 Định nghĩaPython đánh giá các giá trị nhất định là 92 khi trong bối cảnh Boolean. Một quy tắc nhanh chóng của ngón tay cái, là tất cả các giá trị trống rỗng của người dùng được coi là sai, do đó, tất cả đều đánh giá là sai trong bối cảnh boolean.2.14.2 Ưu điểmCác điều kiện sử dụng Booleans Python dễ đọc hơn và ít dễ bị lỗi hơn. Trong hầu hết các trường hợp, họ 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 các tính năng giả mạo của người Viking nếu có thể, ví dụ, 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 sử dụng. 2.16.1 Định nghĩaMột hàm python lồng nhau có thể tham khảo các biến được xác định trong các hàm bao quanh, nhưng không thể gán cho chúng. Các ràng buộc biến đổi đượ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ỳ nhiệm vụ 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 trước khi chuyển nhượng. Nếu một tuyên bố 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 thoải mái cho các lập trình viên Lisp và Sơ đồ (và Haskell và ML và ML). 2.16.3 Nhược điểmCó thể dẫn đến những 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 18, không phải 19.2.16.4 Quyết địnhĐược sử dụng. 2.16.1 Định nghĩaMột hàm python lồng nhau có thể tham khảo các biến được xác định trong các hàm bao quanh, nhưng không thể gán cho chúng. Các ràng buộc biến đổi đượ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ỳ nhiệm vụ 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 trước khi chuyển nhượng. Nếu một tuyên bố 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à:2.16.2 Ưu điểm 0Thường dẫn đến mã rõ ràng hơn, thanh lịch hơn. Đặc biệt thoải mái cho các lập trình viên Lisp và Sơ đồ (và Haskell và ML và ML). 12.16.3 Nhược điểmCó thể dẫn đến những lỗi khó hiểu. Chẳng hạn như ví dụ này dựa trên PEP-0227: Vì vậy, from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
|
Loại hình | Công cộng | Nội bộ |
---|---|---|
Gói | 72 | |
Mô -đun | 72 | Mô -đun |
74 | Các lớp học | 75 |
76 | Các lớp học | |
75 | 76 | Ngoại lệ |
Chức năng | 78 | 79 |
Hằng số toàn cầu/lớp | 72 | Mô -đun |
74 | 72 | Mô -đun |
74 | 76 | Ngoại lệ |
Chức năng | 72 | |
Mô -đun | 72 |
Mô -đun
Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
743.17 Chính
Trong Python,
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
25 cũng như các thử nghiệm đơn vị yêu cầu các mô -đun phải được nhập khẩu. Nếu một tệp được sử dụng như một thực thi, chức năng chính của nó phải nằm trong hàm Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
92 và mã của bạn phải luôn luôn kiểm tra Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
93 trước khi thực hiện chương trình chính của bạn, để nó không được thực thi khi mô -đun được nhập.Khi sử dụng ABSL, hãy sử dụng
Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
94:Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
1Nếu không, sử dụng:
Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
2Tất cả mã ở cấp cao nhất sẽ được thực thi khi mô -đun được nhập. Hãy cẩn thận không gọi các chức năng, tạo đối tượng hoặc thực hiện các hoạt động khác không nên được thực thi khi tệp đang được
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
25ED.3.18 Chiều dài chức năng
Thí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 được đặt trên độ dài chức năng. Nếu một chức năng vượt quá khoảng 40 dòng, hãy nghĩ về việc liệu nó có thể bị phá vỡ mà không gây hại cho cấu trúc của chương trình hay không.
Ngay cả khi chức năng dài của bạn hoạt động hoàn hảo bây giờ, ai đó sửa đổi nó trong một 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ữ các chức năng của bạn ngắn gọn và đơn giản giúp người khác dễ đọ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 chức năng dài và phức tạp khi làm việc với một số mã. Khô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 chứng tỏ là khó khăn, bạn thấy rằng các lỗi rất khó để gỡ lỗi hoặc bạn muốn sử dụng một phần của nó trong một số bối cảnh khác nhau, hãy xem xét việc chia chức năng thành nhỏ hơn và các mảnh có thể quản lý hơn.
3.19 Loại chú thích
3.19.1 Quy tắc chung
Làm quen với PEP-484.
Trong các phương pháp, chỉ chú thích
73 hoặcdef viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str: del beans, eggs # Unused by vikings. return spam + spam + spam
74 nếu cần thiết cho thông tin loại thích hợp. ví dụ.,def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str: del beans, eggs # Unused by vikings. return spam + spam + spam
3Yes: result = [mapping_expr for value in iterable if filter_expr] result = [{'key': value} for value in iterable if a_long_filter_expression(value)] result = [complicated_transform(x) for x in iterable if predicate(x)] descriptive_name = [ transform({'key': key, 'value': value}, color='black') for key, value in generate_iterable(some_input) if complicated_condition_is_met(key, value) ] result = [] for x in range(10): for y in range(5): if x * y > 10: result.append((x, y)) return {x: complicated_transform(x) for x in long_generator_function(parameter) if x is not None} squares_generator = (x**2 for x in range(10)) unique_names = {user.name for user in users if user is not None} eat(jelly_bean for jelly_bean in jelly_beans if jelly_bean.color == 'black')
Tương tự, don lồng cảm thấy buộc phải chú thích giá trị trả về của
98 (trong đóYes: # Reference absl.flags in code with the complete name (verbose). import absl.flags from doctor.who import jodie _FOO = absl.flags.DEFINE_string(...)
98 là tùy chọn hợp lệ duy nhất).def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str: del beans, eggs # Unused by vikings. return spam + spam + spam
Nếu không nên thể hiện bất kỳ biến hoặc loại được trả về nào khác, hãy sử dụng
00.Yes: # Reference flags in code with just the module name (common). from absl import flags from doctor.who import jodie _FOO = flags.DEFINE_string(...)
Bạn không bắt buộc phải chú thích tất cả các chức năng trong một mô -đun.
- Ít nhất là chú thích API công khai của bạn.
- Sử dụng phán đoán để có được sự cân bằng tốt giữa một mặt an toàn và rõ ràng và mặt khác là sự linh hoạt.
- Mã chú thích dễ bị lỗi liên quan đến loại (lỗi trước hoặc độ phức tạp).
- Mã chú thích khó hiểu.
- Mã chú thích vì nó trở nên ổn định từ góc độ loại. Trong nhiều trường hợp, bạn có thể chú thích tất cả các chức năng trong mã trưởng thành mà không mất quá nhiều sự linh hoạt.
3.19.2 Phá vỡ dòng
Cố gắng tuân theo các quy tắc thụt lề hiện có.
Sau khi chú thích, nhiều chữ ký chức năng sẽ trở thành một tham số trên mỗi dòng. Để đảm bảo loại trả về cũng được đưa ra dòng riêng, một dấu phẩy có thể được đặt sau tham số cuối cùng.
Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
4Luôn thích phá vỡ giữa các biến, và không, ví dụ, giữa các 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 đi cho nó.
Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
5Nếu sự kết hợp của tên hàm, tham số cuối cùng và loại trả về quá dài, thụt thêm 4 trong một dòng mới. Khi sử dụng ngắt dòng, thích đặt từng tham số và loại trả về trên các dòng của riêng họ và sắp xếp dấu ngoặc đơn kết thúc với
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
50:Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
6Tùy chọn, loại trả về có thể được đặt trên cùng một dòng với tham số cuối cùng:
Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
7def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
16 cho phép bạn di chuyển dấu ngoặc đơn đóng vào một dòng mới và phù hợp với phần mở đầu, nhưng điều này không thể đọc được.Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
8Như trong các ví dụ trên, không thích phá vỡ các loại. Tuy nhiên, đôi khi chúng quá dài để ở trên một dòng duy nhất (cố gắng giữ cho các loại phụ không bị phá vỡ).
Yes:
result = [mapping_expr for value in iterable if filter_expr]
result = [{'key': value} for value in iterable
if a_long_filter_expression(value)]
result = [complicated_transform(x)
for x in iterable if predicate(x)]
descriptive_name = [
transform({'key': key, 'value': value}, color='black')
for key, value in generate_iterable(some_input)
if complicated_condition_is_met(key, value)
]
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
return {x: complicated_transform(x)
for x in long_generator_function(parameter)
if x is not None}
squares_generator = (x**2 for x in range(10))
unique_names = {user.name for user in users if user is not None}
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
9Nếu một tên và loại quá dài, hãy xem xét sử dụng bí danh cho loại. Phương sách cuối cùng là phá vỡ sau đại tràng và thụt vào 4.
No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
0No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
13.19.3 Khai báo chuyển tiếp
Nếu bạn cần sử dụng 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 lớp bên trong khai báo lớp hoặc nếu bạn sử dụng một lớp được xác định bên dưới - hoặc sử dụng
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
03 cho các trường hợp đơn giản hoặc sử dụng một chuỗi cho tên lớp.No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
23.19.4 Giá trị mặc định
Theo PEP-008, chỉ sử dụng các khoảng trống xung quanh
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
51 cho các đối số có cả chú thích loại và giá trị mặc định.No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
3No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
43.19.5 Nonetype
Trong hệ thống loại Python,
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
05 là loại hạng nhất của nhóm và với mục đích gõ, def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
98 là bí danh cho Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
05. Nếu một đối số có thể là def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
98, nó phải được tuyên bố! Bạn có thể sử dụng Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
09, nhưng nếu chỉ có một loại khác, hãy sử dụng Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
10.Sử dụng rõ ràng
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
10 thay vì ngầm Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
10. Các phiên bản trước đó của PEP 484 cho phép Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
13 được hiểu là Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
14, nhưng đó không còn là hành vi ưa thích.No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
5No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
63.19.6 Bí danh loại
Bạn có thể khai báo bí danh của các loại phức tạp. Tên của một bí danh nên được capword. Nếu bí danh chỉ được sử dụng trong mô -đun này, nó sẽ được _private.
Ví dụ: nếu tên của mô -đun cùng với tên của loại quá dài:
No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
7Các ví dụ khác là các loại lồng nhau phức tạp và nhiều biến trả về từ một hàm (như một tuple).
3.19.7 Bỏ qua các loại
Bạn có thể vô hiệu hóa kiểm tra loại trên một dòng với nhận xét đặc biệt
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
15.Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
16 có tùy chọn vô hiệu hóa cho các lỗi cụ thể (tương tự như lint):No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
83.19.8 Biến gõ
Bài tập được chú thích nếu một biến nội bộ có một loại khó hoặc không thể suy ra, chỉ định loại của nó với một gán được chú thích - sử dụng dấu hai chấm và loại giữa tên và giá trị biến (giống như được thực hiện với các đối số chức năng có giá trị mặc định) :No:
result = [complicated_transform(
x, some_argument=x+1)
for x in iterable if predicate(x)]
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in range(5)
for y in range(5)
if x != y
for z in range(5)
if y != z)
9Kiểu nhận xét 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 của bình luận Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
17 về cuối dòng:def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
003.19.9 Tuples vs Danh sách
Danh sách gõ chỉ có thể chứa các đối tượng thuộc một loại. Các bộ dữ liệu gõ có thể có một loại lặp lại hoặc một số phần tử được đặt với các loại khác nhau. Loại thứ hai thường được sử dụng làm loại trả về từ một hàm.
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
013.19.10 Typevars
Hệ thống loại Python có thuốc generic. Hàm nhà máy
Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
54 là một cách phổ biến để sử dụng chúng.Example:
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
02Một typevar có thể bị hạn chế:
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
03Một biến loại được xác định trước phổ biến trong mô -đun
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
46 là Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
20. Sử dụng nó cho nhiều chú thích có thể là Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
21 hoặc Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
22 và tất cả phải là cùng một loại.def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
04Một typevar phải có tên mô tả, trừ khi nó đáp ứng tất cả các tiêu chí sau:
- không nhìn thấy bên ngoài
- không bị ràng buộc
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
05def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
063.19.11 Các loại chuỗi
Không sử dụng
23 trong mã mới. Nó chỉ có khả năng tương thích Python 2/3.Yes: # Reference flags in code with just the module name (common). from absl import flags from doctor.who import jodie _FOO = flags.DEFINE_string(...)
Sử dụng
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
22 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 Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
21.def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
07Nếu tất cả các loại chuỗi của một hàm luôn giống nhau, ví dụ, nếu loại trả về giống như loại đối số trong mã ở trên, hãy sử dụng bất kỳSTR nào.
3.19.12 Nhập khẩu để gõ
Đối với các ký hiệu từ các mô -đun
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
46 và def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
47 được sử dụng để hỗ trợ phân tích tĩnh và kiểm tra loại, luôn luôn tự nhập biểu tượng. Điều này giữ cho các chú thích chung súc tích hơn và phù hợp với các hoạt động gõ được sử dụng trên toàn thế giới. Bạn được phép nhập rõ ràng để nhập nhiều lớp cụ thể trên một dòng từ các mô -đun def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
46 và def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
47. Bán tại:def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
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ộ, tên trong
def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
46 hoặc def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
47 nên đượ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 hoặc không. Nếu có sự va chạm 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 Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
32.def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
093.19.13 Nhập khẩu có điều kiện
Chỉ sử dụng nhập khẩu có điều kiện trong các trường hợp đặc biệt trong đó nhập khẩu bổ sung cần thiết để kiểm tra loại phải được tránh trong thời gian chạy. Mô hình này không được khuyến khích; Các lựa chọn thay thế như tái cấu trúc mã để cho phép nhập khẩu cấp cao nhất nên được ưu tiên.
Nhập khẩu chỉ cần thiết cho các chú thích loại có thể được đặt trong một khối
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
33.- Các loại nhập khẩu có điều kiện cần được tham chiếu là chuỗi, để tương thích về phía trước với Python 3.6 trong đó các biểu thức chú thích thực sự được đánh giá.
- Chỉ các thực thể được sử dụng chỉ để gõ nên được xác định ở đây; Điều này bao gồm các bí danh. Nếu không, nó sẽ là một lỗi thời gian chạy, vì mô -đun sẽ không được nhập vào thời gian chạy.
- Khối phải đúng sau khi nhập khẩu bình thường.
- Không nên có dòng trống trong danh sách nhập khẩu.
- Sắp xếp danh sách này như thể nó là một danh sách nhập khẩu thường xuyên.
10def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str: del beans, eggs # Unused by vikings. return spam + spam + spam
3.19.14 Phụ thuộc tròn
Sự phụ thuộc tròn được gây ra bởi việc gõ là mùi mã. 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 tròn, 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 bởi 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 phụ thuộc tròn bằng
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
00. Đặt bí danh với 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 bất kỳ là bất kỳ). Các định nghĩa bí danh nên được tách ra khỏi nhập lần cuối theo một dòng.def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
113.19.15 Generics
Khi chú thích, thích chỉ định các tham số loại cho các loại chung; Mặt khác, các tham số của generics sẽ được giả định là
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
00.def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
12def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
13Nếu tham số loại tốt nhất cho một chung là
Yes:
# Reference flags in code with just the module name (common).
from absl import flags
from doctor.who import jodie
_FOO = flags.DEFINE_string(...)
00, hãy làm cho nó rõ ràng, nhưng hãy nhớ rằng trong nhiều trường hợp Yes:
# Reference absl.flags in code with the complete name (verbose).
import absl.flags
from doctor.who import jodie
_FOO = absl.flags.DEFINE_string(...)
54 có thể phù hợp hơn:def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
14def viking_cafe_order(spam: str, beans: str, eggs: Optional[str] = None) -> str:
del beans, eggs # Unused by vikings.
return spam + spam + spam
154 từ chia tay
Được nhất quán.
Nếu bạn 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 không gian xung quanh tất cả các toán tử số học của họ, bạn cũng nên như vậy.Nếu bình luận của họ có những hộp băm nhỏ xung quanh họ, hãy làm cho ý kiến của bạn có một số hộp băm nhỏ xung quanh chúng.
Quan điểm của việc có hướng dẫn theo phong cách là có một từ vựng chung về mã hóa để mọi người có thể tập trung vào những gì bạn nói thay vì 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 biệt đáng kể so với mã hiện có xung quanh nó, nó sẽ đưa người đọc ra khỏi nhịp điệu của họ khi họ đi đọc nó.Tránh điều này.