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ữ Python
2. 1 xơ vải
Chạy
pylint --list-msgs31 qua mã của bạn bằng cách sử dụng pylintrc này
2. 1. 1 Định nghĩa
pylint --list-msgs31 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ểm
Bắ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
pylint --list-msgs31 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 hoặc sửa chữa nó
2. 1. 4 Quyết định
Đảm bảo bạn chạy
pylint --list-msgs31 trên mã của mình
Loạ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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
Mỗi cảnh báo của
pylint --list-msgs31 được xác định bằng tên tượng trưng [
pylint --list-msgs36] Các cảnh báo dành riêng cho Google bắt đầu bằng
pylint --list-msgs37
Nế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 cảnh báo
pylint --list-msgs31 bằng cách thực hiện
pylint --list-msgs
Để có thêm thông tin về một tin nhắn cụ thể, hãy sử dụng
pylint --list-msgs0
Thích
pylint --list-msgs39 hơn mẫu cũ hơn không dùng nữa
pylint --list-msgs40
Có 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ụ
pylint --list-msgs3
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 '
pylint --list-msgs41' 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 '
pylint --list-msgs42' hoặc gán chúng cho '
pylint --list-msgs41'. 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ụng
2. 2 nhập khẩu
Chỉ sử dụng các câu lệnh
pylint --list-msgs44 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ĩa
Cơ chế tái sử dụng để chia sẻ mã từ mô-đun này sang mô-đun khác
2. 2. 2 Ưu điểm
Quy ướ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ểm
Tê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
- Sử dụng
pylint --list-msgs
48 để nhập các gói và mô-đun - Sử dụng
pylint --list-msgs
49 trong đópylint --list-msgs
47 là tiền tố gói vàpylint --list-msgs
51 là tên mô-đun không có tiền tố - Sử dụng
pylint --list-msgs
52 nếu hai mô-đun có tênpylint --list-msgs
51 sẽ được nhập, nếupylint --list-msgs
51 xung đột với tên cấp cao nhất được xác định trong mô-đun hiện tại hoặc nếupylint --list-msgs
51 là một tên dài bất tiện - Chỉ sử dụng
pylint --list-msgs
56 khipylint --list-msgs
57 là từ viết tắt tiêu chuẩn [e. g. ,pylint --list-msgs
58 chopylint --list-msgs
59]
Ví dụ: mô-đun
pylint --list-msgs60 có thể được nhập như sau
pylint --list-msgs4
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
- Các ký hiệu từ các mô-đun sau được sử dụng để hỗ trợ phân tích tĩnh và kiểm tra kiểu
- Mô-đun
pylint --list-msgs
63
- Mô-đun
- Chuyển hướng từ
2. 3 gói
Nhập từng mô-đun bằng vị trí tên đường dẫn đầy đủ của mô-đun
2. 3. 1 Ưu điểm
Trá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ểm
Là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 định
Tấ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
pylint --list-msgs6
pylint --list-msgs7
[giả sử tệp này tồn tại trong
pylint --list-msgs64 nơi mà
pylint --list-msgs65 cũng tồn tại]
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin0
Thư mục chứa tệp nhị phân chính không nên được coi là trong
pylint --list-msgs66 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
pylint --list-msgs67 đề cập đến một bên thứ ba hoặc gói cấp cao nhất có tên là
pylint --list-msgs68, không phải là một
pylint --list-msgs65 cục bộ
2. 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ĩa
Ngoạ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ểm
Luồ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ểm
Có 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 định
Ngoại lệ phải tuân theo các điều kiện nhất định
Sử dụng các lớp ngoại lệ tích hợp khi nó hợp lý. Ví dụ: tăng
pylint --list-msgs
70 để chỉ ra lỗi lập trình như điều kiện tiên quyết bị vi phạm [chẳng hạn như nếu bạn được thông qua số âm nhưng yêu cầu số dương]. Không sử dụng câu lệnhpylint --list-msgs
71 để xác thực giá trị đối số của API công khai.pylint --list-msgs
71 được sử dụng để đảm bảo tính đúng đắn bên trong, không bắt buộc sử dụng đúng cách cũng như không chỉ ra rằng một số sự kiện bất ngờ đã xảy ra. Nếu một ngoại lệ được mong muốn trong các trường hợp sau, hãy sử dụng câu lệnh nâng cao. Ví dụdict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
8dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
9Thư viện hoặc gói có thể xác định ngoại lệ của riêng họ. Khi làm như vậy, họ phải kế thừa từ một lớp ngoại lệ hiện có. Tên ngoại lệ phải kết thúc bằng ________ 073 và không nên lặp lại [________ 074]
Không bao giờ sử dụng câu lệnh bắt tất cả
pylint --list-msgs
75 hoặc bắtpylint --list-msgs
76 hoặcpylint --list-msgs
77, trừ khi bạn- tăng lại ngoại lệ, hoặc
- tạo một điểm cách ly trong chương trình nơi các ngoại lệ không được lan truyền mà thay vào đó được ghi lại và loại bỏ, chẳng hạn như bảo vệ một chuỗi khỏi sự cố bằng cách bảo vệ khối ngoài cùng của nó
Python rất khoan dung về vấn đề này và
pylint --list-msgs
75 sẽ thực sự nắm bắt mọi thứ kể cả tên sai chính tả, sys. exit[], Ctrl+C ngắt, lỗi nhỏ nhất và tất cả các loại ngoại lệ khác mà bạn đơn giản là không muốn nắm bắtGiảm thiểu số lượng mã trong khối
pylint --list-msgs
79/_______080. Phần thân củapylint --list-msgs
79 càng lớn thì càng có nhiều khả năng một ngoại lệ sẽ được đưa ra bởi một dòng mã mà bạn không mong đợi sẽ đưa ra một ngoại lệ. Trong những trường hợp đó, khốipylint --list-msgs
79/pylint --list-msgs
80 ẩn một lỗi thực sựSử dụng mệnh đề
pylint --list-msgs
84 để thực thi mã cho dù có hay không một ngoại lệ được đưa ra trong khốipylint --list-msgs
79. Điều này thường hữu ích cho việc dọn dẹp, tôi. e. , đóng một tập tin
2. 5 trạng thái toàn cầu có thể thay đổi
Tránh trạng thái toàn cầu có thể thay đổi
2. 5. 1 Định nghĩa
Cá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ểm
Thỉnh thoảng hữu ích
2. 5. 3 nhược điểm
Phá vỡ đóng gói. Thiết kế như vậy có thể gây khó khăn cho việc đạt được các mục tiêu hợp lệ. Ví dụ: nếu trạng thái chung được sử dụng để quản lý kết nối cơ sở dữ liệu, thì việc kết nối đồng thời với hai cơ sở dữ liệu khác nhau [chẳng hạn như đối với sự khác biệt về tính toán trong quá trình di chuyển] sẽ trở nên khó khăn. Các vấn đề tương tự dễ dàng phát sinh với các cơ quan đăng ký toàn cầu
Có khả năng thay đổi hành vi của mô-đun trong quá trình nhập, vì việc gán cho các biến toàn cục được thực hiện khi mô-đun được nhập lần đầu
2. 5. 4 Quyết định
Trá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 bên trong bằng cách thêm một
pylint --list-msgs41 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ụ.
pylint --list-msgs87 cho hằng số sử dụng nội bộ hoặc
pylint --list-msgs88 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ưới
2. 6 Các lớp và hàm lồng nhau/cục bộ/bên trong
Cá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ĩa
Mộ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ểm
Cho 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ểm
Cá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 định
Họ ổ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
pylint --list-msgs89 hoặc
pylint --list-msgs90. 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ệm
2. 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ĩa
Khả 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 vùng chứa và trình vòng lặp mà không cần sử dụng các vòng lặp truyền thống,
pylint --list-msgs91,
pylint --list-msgs92 hoặc
pylint --list-msgs93
2. 7. 2 Ưu điểm
Việ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ểm
Có 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 đề
pylint --list-msgs94, biểu thức bộ lọc. Nhiều mệnh đề
pylint --list-msgs94 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
pylint --list-msgs0
pylint --list-msgs1
2. 8 Iterator và Operator mặc định
Sử 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ĩa
Các loại vùng chứa, như từ điển và danh sách, xác định các trình 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ểm
Cá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ểm
Bạ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 định
Sử 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ó
pylint --list-msgs2
pylint --list-msgs3
2. 9 máy phát điện
Sử dụng máy phát điện khi cần thiết
2. 9. 1 Định nghĩa
Hà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ểm
Mã đơ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ểm
Cá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 định
Khỏe. Sử dụng "Năng suất. " thay vì "Trả về. " trong chuỗi tài liệu cho các hàm tạo
Nếu trình tạo quản lý một tài nguyên đắt tiền, hãy đảm bảo buộc dọn sạch
Một cách hay để dọn dẹp là bọc trình tạo bằng trình quản lý ngữ cảnh PEP-0533
2. 10 Hàm Lambda
Được rồi cho một lớp lót. Thích các biểu thức trình tạo hơn
pylint --list-msgs91 hoặc
pylint --list-msgs92 với một
pylint --list-msgs93
2. 10. 1 Định nghĩa
Lambdas đị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ểm
Thuận tiện
2. 10. 3 nhược điểm
Khó đọ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
pylint --list-msgs99 thay vì các hàm lambda. Ví dụ: thích
pylint --list-msgs000 hơn là
pylint --list-msgs001
2. 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ĩa
Biể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ụ.
pylint --list-msgs002
2. 11. 2 Ưu điểm
Ngắn gọn và thuận tiện hơn câu lệnh if
2. 11. 3 nhược điểm
Có 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
pylint --list-msgs4
pylint --list-msgs5
2. 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ĩa
Bạ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. ,
pylint --list-msgs003. Nếu
pylint --list-msgs004 được gọi chỉ với một đối số, thì
pylint --list-msgs005 được đặt thành 0. Nếu nó được gọi với hai đối số, thì
pylint --list-msgs005 có giá trị của đối số thứ hai
2. 12. 2 Ưu điểm
Thườ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ểm
Cá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
pylint --list-msgs6
pylint --list-msgs7
2. 13 thuộc tính
Cá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ĩa
Mộ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
- Cho phép API gán và truy cập thuộc tính thay vì gọi phương thức
- Có thể được sử dụng để tạo thuộc tính chỉ đọc
- Cho phép tính toán lười biếng
- Cung cấp một cách để duy trì giao diện chung của một lớp khi các phần bên trong phát triển độc lập với người dùng lớp
2. 13. 3 nhược điểm
- Có thể ẩn các tác dụng phụ giống như quá tải toán tử
- Có thể gây nhầm lẫn cho các lớp con
2. 13. 4 Quyết định
Cá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 thuộc tính để vừa lấy vừa đặ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
pylint --list-msgs007. Thực hiện thủ công một bộ mô tả thuộc tính được coi là một
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 tính toán mà một lớp con có thể muốn ghi đè và mở rộng
2. 14 Đánh giá Đúng/Sai
Sử dụng sai "ngầm" nếu có thể
2. 14. 1 Định nghĩa
Python đánh giá các giá trị nhất định là
pylint --list-msgs008 khi ở trong ngữ cảnh boolean. Một "quy tắc ngón tay cái" nhanh chóng là tất cả các giá trị "trống" được coi là sai, vì vậy tất cả
pylint --list-msgs009 đều được đánh giá là sai trong ngữ cảnh boolean
2. 14. 2 Ưu điểm
Cá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ểm
Có thể trông lạ đối với các nhà phát triển C/C++
2. 14. 4 Quyết định
Sử dụng false "ngầm" nếu có thể, e. g. ,
pylint --list-msgs010 thay vì
pylint --list-msgs011. Có một vài cảnh báo mà bạn nên ghi nhớ mặc dù
Luôn sử dụng
pylint --list-msgs
012 [hoặcpylint --list-msgs
013] để kiểm tra giá trịpylint --list-msgs
014. e. g. , khi kiểm tra xem một biến hoặc đối số mặc định làpylint --list-msgs
014 có được đặt thành một số giá trị khác không. Giá trị khác có thể là một giá trị sai trong ngữ cảnh booleanKhông bao giờ so sánh một biến boolean với
pylint --list-msgs
008 bằng cách sử dụngpylint --list-msgs
017. Sử dụngpylint --list-msgs
018 để thay thế. Nếu bạn cần phân biệtpylint --list-msgs
008 vớipylint --list-msgs
014 thì hãy xâu chuỗi các biểu thức, chẳng hạn nhưpylint --list-msgs
021Đối với các chuỗi [chuỗi, danh sách, bộ dữ liệu], hãy sử dụng thực tế là các chuỗi trống là sai, do đó,
pylint --list-msgs
022 vàpylint --list-msgs
023 được ưu tiên hơn so vớipylint --list-msgs
024 vàpylint --list-msgs
025 tương ứngKhi xử lý các số nguyên, sai ẩn có thể gây ra nhiều rủi ro hơn là lợi ích [i. e. , vô tình xử lý
pylint --list-msgs
014 là 0]. Bạn có thể so sánh một giá trị đã biết là một số nguyên [và không phải là kết quả củapylint --list-msgs
027] với số nguyên 0pylint --list-msgs
8pylint --list-msgs
9Lưu ý rằng
pylint --list-msgs
028 [tôi. e. ,pylint --list-msgs
029 dưới dạng chuỗi] đánh giá là trueLưu ý rằng các mảng Numpy có thể đưa ra một ngoại lệ trong ngữ cảnh boolean ngầm định. Ưu tiên thuộc tính
pylint --list-msgs
030 khi kiểm tra sự trống rỗng của mộtpylint --list-msgs
031 [e. g.pylint --list-msgs
032]
2. 16 Phạm vi từ vựng
Được rồi để sử dụng
2. 16. 1 Định nghĩa
Một hàm Python lồng nhau có thể tham chiếu đến các biến được xác định trong các hàm kèm theo, nhưng không thể gán cho chúng. Các liên kết biến được giải quyết bằng cách sử dụng phạm vi từ vựng, nghĩa là dựa trên văn bản chương trình tĩnh. Bất kỳ sự gán nào cho một tên trong một khối sẽ khiến Python coi tất cả các tham chiếu đến tên đó là một biến cục bộ, ngay cả khi việc sử dụng có trước sự gán. Nếu một khai báo toàn cầu xảy ra, tên được coi là một biến toàn cầu
Một ví dụ về việc sử dụng tính năng này là
pylint --list-msgs00
2. 16. 2 Ưu điểm
Thường dẫn đến mã rõ ràng hơn, thanh lịch hơn. Đặc biệt thoải mái với Lisp và Scheme có kinh nghiệm [và Haskell và ML và. ] lập trình viên
2. 16. 3 nhược điểm
Có thể dẫn đến các lỗi khó hiểu. Chẳng hạn như ví dụ này dựa trên PEP-0227
pylint --list-msgs01
Vì vậy,
pylint --list-msgs033 sẽ in ra
pylint --list-msgs034, không phải
pylint --list-msgs035
2. 16. 4 Quyết định
Được rồi để sử dụng
2. 17 Trình trang trí chức năng và phương thức
Sử dụng decorators một cách thận trọng khi có một lợi thế rõ ràng. Tránh
pylint --list-msgs036 và hạn chế sử dụng
pylint --list-msgs037
2. 17. 1 Định nghĩa
[một. k. một "ký hiệu
pylint --list-msgs038"]. Một trình trang trí phổ biến là
pylint --list-msgs007, đượ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
pylint --list-msgs040, điều này
pylint --list-msgs02
tương đương với
pylint --list-msgs03
2. 17. 2 Ưu điểm
Chỉ đị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ểm
Trì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 khẩu. Lỗi trong mã trang trí hầu như không thể phục hồi từ
2. 17. 4 Quyết định
Sử 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ừ
pylint --list-msgs041 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ợp
Trì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
pylint --list-msgs036 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ô-đun
Chỉ sử dụng
pylint --list-msgs037 khi viết một hàm tạo có tên hoặc một quy trình dành riêng cho lớp để sửa đổi trạng thái chung cần thiết, chẳng hạn như bộ đệm trên toàn quy trình
2. 18 luồng
Khô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
pylint --list-msgs044 hoặc
pylint --list-msgs045 được triển khai dưới dạng các 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
pylint --list-msgs046 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à
pylint --list-msgs047 thay vì sử dụng các khóa cấp thấp hơn
2. 19 Tính năng nguồn
Tránh các tính năng này
2. 19. 1 Định nghĩa
Python là một ngôn ngữ cực kỳ linh hoạt và cung cấp cho bạn nhiều tính năng ưa thích như siêu dữ liệu tùy chỉnh, quyền truy cập vào mã byte, biên dịch nhanh, kế thừa động, sửa chữa đối tượng, hack nhập, phản chiếu [e. g. một số cách sử dụng của
pylint --list-msgs048], sửa đổi nội bộ hệ thống, phương pháp
pylint --list-msgs049 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ểm
Rấ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ả ban đầu], 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 định
Trá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ụ:
pylint --list-msgs050,
pylint --list-msgs051 và
pylint --list-msgs052]
2. 20 con trăn hiện đại. từ __future__ nhập khẩu
Cá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ĩa
Có thể bật một số tính năng hiện đại hơn thông qua câu lệnh
pylint --list-msgs053 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 lai
2. 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ểm
Mã 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 định
từ __future__ nhập khẩuViệc sử dụng các câu lệnh
pylint --list-msgs053 đượ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 có các tính năng bị ẩn đằng sau lần nhập
pylint --list-msgs055, 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
pylint --list-msgs04
Để 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 báo cáo nhập khẩu
pylint --list-msgs056 khác khi bạn thấy phù hợp
2. 21 Loại mã chú thích
Bạ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ĩa
Chú thích kiểu [hoặc "gợi ý kiểu"] dành cho các đối số của hàm hoặc phương thức và giá trị trả về
pylint --list-msgs05
Bạn cũng có thể khai báo loại biến bằng cú pháp PEP-526 tương tự
pylint --list-msgs06
2. 21. 2 Ưu điểm
Loạ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ểm
Bạ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 định
Bạn được khuyến khích bật phân tích kiểu Python khi cập nhật mã. Khi thêm hoặc sửa đổi API công khai, hãy bao gồm các chú thích loại và cho phép kiểm tra qua pytype trong hệ thống xây dựng. Vì phân tích tĩnh còn tương đối mới đối với Python, chúng tôi thừa nhận rằng các tác dụng phụ không mong muốn [chẳng hạn như các loại được suy luận sai] có thể ngăn một số dự án áp dụng. Trong những trường hợp đó, tác giả được khuyến khích thêm nhận xét bằng TODO hoặc liên kết đến lỗi mô tả [các] sự cố hiện đang ngăn cản việc áp dụng chú thích loại trong tệp BUILD hoặc trong chính mã khi thích hợp
3 quy tắc kiểu Python
3. 1 dấu chấm phẩy
Không kết thúc dòng của bạn bằng dấu chấm phẩy và không sử dụng dấu chấm phẩy để đặt hai câu lệnh trên cùng một dòng
3. 2 Chiều dài dòng
Độ dài dòng tối đa là 80 ký tự
Ngoại lệ rõ ràng đối với giới hạn 80 ký tự
- Báo cáo nhập khẩu dài
- URL, tên đường dẫn hoặc cờ dài trong nhận xét
- Các hằng số cấp mô-đun chuỗi dài không chứa khoảng trắng sẽ gây bất tiện khi chia thành các dòng như URL hoặc tên đường dẫn
- Pylint vô hiệu hóa bình luận. [e. g.
pylint --list-msgs
057]
- Pylint vô hiệu hóa bình luận. [e. g.
Không sử dụng tiếp tục dòng gạch chéo ngược ngoại trừ câu lệnh
pylint --list-msgs058 yêu cầu ba trình quản lý ngữ cảnh trở lên
Tận dụng Python. Nếu cần, bạn có thể thêm một cặp dấu ngoặc đơn xung quanh một biểu thức
pylint --list-msgs07
Khi 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
pylint --list-msgs08
Trong 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
pylint --list-msgs09
pylint --list-msgs30
Có thể sử dụng tiếp tục dấu gạch chéo ngược khi xác định câu lệnh
pylint --list-msgs058 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
pylint --list-msgs058 lồng nhau
pylint --list-msgs31
pylint --list-msgs32
pylint --list-msgs33
Lưu ý về sự thụt đầu dòng của các phần tử trong các ví dụ tiếp tục dòng ở trên;
Trong tất cả các trường hợp khác khi một dòng vượt quá 80 ký tự và trình định dạng tự động yapf không giúp đưa dòng xuống dưới giới hạn, thì dòng đó được phép vượt quá mức tối đa này. Các tác giả được khuyến khích ngắt dòng theo cách thủ công theo ghi chú ở trên khi thấy hợp lý
3. 3 dấu ngoặc đơn
Sử dụng dấu ngoặc đơn một cách tiết kiệm
Nó là tốt, mặc dù không bắt buộc, để sử dụng dấu ngoặc đơn xung quanh bộ dữ liệu. Không sử dụng chúng trong các câu lệnh trả về hoặc câu lệnh có điều kiện trừ khi sử dụng dấu ngoặc đơn để tiếp tục dòng ngụ ý hoặc để chỉ ra một bộ
pylint --list-msgs34
pylint --list-msgs35
3. 4 Thụt đầu dòng
Thụt lề các khối mã của bạn với 4 dấu cách
Không bao giờ sử dụng các tab. Việc tiếp tục dòng ngụ ý phải căn chỉnh các phần tử được bao theo chiều dọc [xem] hoặc sử dụng thụt lề 4 dấu cách treo. Dấu ngoặc đóng [tròn, vuông hoặc cong] có thể được đặt ở cuối biểu thức hoặc trên các dòng riêng biệt, nhưng sau đó phải được thụt vào giống như dòng có dấu ngoặc mở tương ứng
pylint --list-msgs36
pylint --list-msgs37
3. 4. 1 Dấu phẩy ở cuối dãy các mục?
Dấu phẩy ở cuối trong chuỗi các mục chỉ được khuyến nghị khi mã thông báo vùng chứa đóng
pylint --list-msgs061,
pylint --list-msgs062 hoặc
pylint --list-msgs063 không xuất hiện trên cùng một dòng với phần tử cuối cùng. Sự hiện diện của dấu phẩy ở cuối cũng được sử dụng như một gợi ý cho trình định dạng tự động mã Python YAPF của chúng tôi để hướng dẫn nó tự động định dạng vùng chứa các mục thành một mục trên mỗi dòng khi có _____1064 sau phần tử cuối cùng
pylint --list-msgs38
pylint --list-msgs39
3. 5 dòng trống
Hai dòng trống giữa các định nghĩa cấp cao nhất, có thể là định nghĩa hàm hoặc lớp. Một dòng trống giữa các định nghĩa phương thức và giữa chuỗi tài liệu của
pylint --list-msgs065 và phương thức đầu tiên. Không có dòng trống nào sau dòng
pylint --list-msgs066. Sử dụng các dòng trống đơn khi bạn đánh giá phù hợp trong các hàm hoặc phương thức
Các dòng trống không cần phải được neo vào định nghĩa. Ví dụ: các nhận xét liên quan ngay trước các định nghĩa hàm, lớp và phương thức có thể có ý nghĩa. Cân nhắc xem nhận xét của bạn có thể hữu ích hơn như một phần của chuỗi tài liệu không
3. 6 Khoảng trắng
Thực hiện theo các quy tắc đánh máy tiêu chuẩn để sử dụng khoảng trắng xung quanh dấu chấm câu
Không có khoảng trắng bên trong dấu ngoặc đơn, dấu ngoặc hoặc dấu ngoặc nhọn
pylint --list-msgs40
pylint --list-msgs41
Không có khoảng trắng trước dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm. Sử dụng khoảng trắng sau dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm, ngoại trừ ở cuối dòng
pylint --list-msgs42
pylint --list-msgs43
Không có khoảng trắng trước dấu ngoặc đơn/ngoặc mở bắt đầu danh sách đối số, lập chỉ mục hoặc cắt
pylint --list-msgs44
pylint --list-msgs45
pylint --list-msgs46
pylint --list-msgs47
Không có khoảng trắng ở cuối
Bao quanh các toán tử nhị phân với một khoảng trắng ở hai bên để gán [
pylint --list-msgs067], so sánh [
pylint --list-msgs068] và Booleans [
pylint --list-msgs069]. Sử dụng khả năng phán đoán tốt hơn của bạn để chèn khoảng trắng xung quanh các toán tử số học [________ 1070, ________ 1071, ______ 1072,
pylint --list-msgs073,
pylint --list-msgs074,
pylint --list-msgs075,
pylint --list-msgs076,
pylint --list-msgs038]
pylint --list-msgs48
pylint --list-msgs49
Không bao giờ sử dụng khoảng trắng xung quanh
pylint --list-msgs067 khi chuyển đối số từ khóa hoặc xác định giá trị tham số mặc định, với một ngoại lệ. , hãy sử dụng khoảng trắng xung quanh
pylint --list-msgs067 cho giá trị tham số mặc định
pylint --list-msgs60
pylint --list-msgs61
Không sử dụng khoảng trắng để sắp xếp theo chiều dọc mã thông báo trên các dòng liên tiếp, vì nó sẽ trở thành gánh nặng bảo trì [áp dụng cho
pylint --list-msgs080,
pylint --list-msgs081,
pylint --list-msgs067, v.v. ]
pylint --list-msgs62
pylint --list-msgs63
3. 7 dòng Shebang
Hầu hết các tệp
pylint --list-msgs083 không cần bắt đầu bằng dòng
pylint --list-msgs084. Bắt đầu tệp chính của chương trình với
pylint --list-msgs085 [để hỗ trợ virtualenv] hoặc
pylint --list-msgs086 mỗi PEP-394
Dòng này được nhân sử dụng để tìm trình thông dịch Python, nhưng bị Python bỏ qua khi nhập mô-đun. Nó chỉ cần thiết trên một tệp dự định được thực thi trực tiếp
3. 8 Nhận xét và Tài liệu
Đảm bảo sử dụng đúng kiểu cho mô-đun, hàm, chuỗi tài liệu phương thức và nhận xét nội tuyến
3. 8. 1 tài liệu
Python sử dụng docstrings để viết mã tài liệu. Chuỗi tài liệu là một chuỗi là câu lệnh đầu tiên trong gói, mô-đun, lớp hoặc hàm. Các chuỗi này có thể được trích xuất tự động thông qua thành viên
pylint --list-msgs087 của đối tượng và được sử dụng bởi
pylint --list-msgs041. [Hãy thử chạy
pylint --list-msgs041 trên mô-đun của bạn để xem nó trông như thế nào. ] Luôn sử dụng định dạng ba trích dẫn kép
pylint --list-msgs090 cho các chuỗi tài liệu [theo PEP 257]. Chuỗi tài liệu phải được tổ chức dưới dạng một dòng tóm tắt [một dòng vật lý không quá 80 ký tự] được kết thúc bằng dấu chấm, dấu chấm hỏi hoặc dấu chấm than. Khi viết thêm [khuyến khích], dòng này phải được theo sau bởi một dòng trống, tiếp theo là phần còn lại của chuỗi tài liệu bắt đầu ở cùng vị trí con trỏ với trích dẫn đầu tiên của dòng đầu tiên. Có nhiều hướng dẫn định dạng hơn cho các tài liệu bên dưới
3. 8. 2 mô-đun
Mỗi tệp phải chứa giấy phép soạn sẵn. Chọn bản soạn sẵn thích hợp cho giấy phép được dự án sử dụng [ví dụ: Apache 2. 0, BSD, LGPL, GPL]
Các tệp phải bắt đầu bằng một chuỗi tài liệu mô tả nội dung và cách sử dụng mô-đun
pylint --list-msgs643. 8. 2. 1 mô-đun thử nghiệm
Không bắt buộc phải có chuỗi tài liệu cấp mô-đun cho các tệp thử nghiệm. Chúng chỉ nên được đưa vào khi có thông tin bổ sung có thể được cung cấp
Các ví dụ bao gồm một số chi tiết cụ thể về cách chạy thử nghiệm, giải thích về mẫu thiết lập bất thường, sự phụ thuộc vào môi trường bên ngoài, v.v.
pylint --list-msgs65
Không nên sử dụng các chuỗi tài liệu không cung cấp bất kỳ thông tin mới nào
pylint --list-msgs66
3. 8. 3 Hàm và Phương thức
Trong phần này, "hàm" có nghĩa là một phương thức, chức năng, trình tạo hoặc thuộc tính
Một chuỗi tài liệu là bắt buộc đối với mọi chức năng có một hoặc nhiều thuộc tính sau
- là một phần của API công khai
- kích thước không tầm thường
- logic không rõ ràng
Một chuỗi tài liệu phải cung cấp đủ thông tin để viết lệnh gọi đến hàm mà không cần đọc mã của hàm. Chuỗi tài liệu phải mô tả cú pháp gọi của hàm và ngữ nghĩa của nó, nhưng nói chung không phải là chi tiết triển khai của nó, trừ khi những chi tiết đó có liên quan đến cách sử dụng hàm. Ví dụ: một hàm thay đổi một trong các đối số của nó dưới dạng tác dụng phụ cần lưu ý rằng trong chuỗi tài liệu của nó. Mặt khác, các chi tiết tinh tế nhưng quan trọng về việc triển khai chức năng không liên quan đến người gọi sẽ được thể hiện dưới dạng nhận xét bên cạnh mã tốt hơn so với trong chuỗi tài liệu của chức năng
Chuỗi tài liệu có thể là kiểu mô tả [
pylint --list-msgs091] hoặc kiểu mệnh lệnh [
pylint --list-msgs092], nhưng kiểu này phải nhất quán trong một tệp. Chuỗi tài liệu cho bộ mô tả dữ liệu
pylint --list-msgs007 phải sử dụng cùng kiểu với chuỗi tài liệu cho một thuộc tính hoặc [
pylint --list-msgs094, thay vì
pylint --list-msgs095]
Một phương thức ghi đè một phương thức từ lớp cơ sở có thể có một chuỗi tài liệu đơn giản gửi trình đọc đến chuỗi tài liệu của phương thức được ghi đè, chẳng hạn như
pylint --list-msgs096. Cơ sở lý luận là không cần phải lặp lại ở nhiều nơi tài liệu đã có trong chuỗi tài liệu của phương thức cơ sở. Tuy nhiên, nếu hành vi của phương thức ghi đè về cơ bản khác với phương thức bị ghi đè hoặc cần cung cấp thông tin chi tiết [e. g. , ghi lại các tác dụng phụ bổ sung], một chuỗi tài liệu có ít nhất những điểm khác biệt đó là bắt buộc đối với phương thức ghi đè
Một số khía cạnh của một chức năng nên được ghi lại trong các phần đặc biệt, được liệt kê bên dưới. Mỗi phần bắt đầu bằng một dòng tiêu đề, kết thúc bằng dấu hai chấm. Tất cả các phần không phải là tiêu đề nên duy trì thụt lề treo hai hoặc bốn khoảng trắng [nhất quán trong một tệp]. Các phần này có thể được bỏ qua trong trường hợp tên và chữ ký của hàm đủ thông tin để có thể mô tả chính xác bằng cách sử dụng chuỗi tài liệu một dòng
. Liệt kê từng tham số theo tên. Mô tả phải theo sau tên và được phân tách bằng dấu hai chấm, sau đó là khoảng trắng hoặc xuống dòng. Nếu mô tả quá dài để vừa với một dòng 80 ký tự, hãy sử dụng thụt lề treo nhiều hơn 2 hoặc 4 khoảng trắng so với tên tham số [nhất quán với phần còn lại của chuỗi tài liệu trong tệp]. Mô tả phải bao gồm [các] loại bắt buộc nếu mã không chứa chú thích loại tương ứng. Nếu một hàm chấp nhận
pylint --list-msgs097 [danh sách đối số có độ dài thay đổi] và/hoặc
pylint --list-msgs098 [đối số từ khóa tùy ý], thì chúng phải được liệt kê là
pylint --list-msgs097 và
pylint --list-msgs098
. Mô tả loại và ngữ nghĩa của giá trị trả về. Nếu hàm chỉ trả về Không thì không cần phần này. Nó cũng có thể được bỏ qua nếu chuỗi tài liệu bắt đầu bằng Returns hoặc Yields [e. g.
pylint --list-msgs301] và câu mở đầu đủ để mô tả giá trị trả về. Không bắt chước 'kiểu NumPy' [ví dụ], kiểu này thường ghi lại giá trị trả về của bộ dữ liệu như thể đó là nhiều giá trị trả về với các tên riêng lẻ [không bao giờ đề cập đến bộ dữ liệu]. Thay vào đó, hãy mô tả một giá trị trả về như. "Trở về. Một bộ [mat_a, mat_b], trong đó mat_a là. , và. ". Các tên phụ trợ trong chuỗi tài liệu không nhất thiết phải tương ứng với bất kỳ tên nội bộ nào được sử dụng trong thân hàm [vì chúng không phải là một phần của API]
. Liệt kê tất cả các ngoại lệ có liên quan đến giao diện theo sau là mô tả. Sử dụng tên ngoại lệ tương tự + dấu hai chấm + dấu cách hoặc dòng mới và kiểu thụt lề treo như được mô tả trong Args. Bạn không nên ghi lại các trường hợp ngoại lệ được nêu ra nếu API được chỉ định trong chuỗi tài liệu bị vi phạm [vì điều này nghịch lý sẽ tạo ra hành vi vi phạm phần API của API]
pylint --list-msgs67
Tương tự, biến thể này trên
pylint --list-msgs302 với ngắt dòng cũng được cho phép
pylint --list-msgs68
3. 8. 4 lớp
Các lớp nên có một chuỗi tài liệu bên dưới định nghĩa lớp mô tả lớp. Nếu lớp của bạn có các thuộc tính công khai, thì chúng phải được ghi lại ở đây trong phần
pylint --list-msgs303 và tuân theo cùng định dạng như một phần
pylint --list-msgs69
Tất cả các chuỗi tài liệu lớp phải bắt đầu bằng một bản tóm tắt một dòng mô tả nội dung mà thể hiện của lớp đại diện. Điều này ngụ ý rằng các lớp con của
pylint --list-msgs76 cũng nên mô tả ngoại lệ đại diện cho cái gì chứ không phải bối cảnh mà nó có thể xảy ra. Chuỗi tài liệu lớp không được lặp lại thông tin không cần thiết, chẳng hạn như lớp là một lớp
pylint --list-msgs70
pylint --list-msgs71
3. 8. 5 Khối và Nhận xét Nội tuyến
Nơi cuối cùng để có nhận xét là ở những phần phức tạp của mã. Nếu bạn phải giải thích nó trong lần xem xét mã tiếp theo, bạn nên bình luận ngay bây giờ. Các hoạt động phức tạp nhận được một vài dòng nhận xét trước khi các hoạt động bắt đầu. Những người không rõ ràng nhận được bình luận ở cuối dòng
pylint --list-msgs72
Để 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
pylint --list-msgs081, 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
pylint --list-msgs73
3. 8. 6 Dấu câu, Chính tả và Ngữ pháp
Chú ý đế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ây
Sử dụng một , toán tử
pylint --list-msgs075 hoặc phương thức
pylint --list-msgs308 để đị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
pylint --list-msgs070 thì được nhưng không định dạng với
pylint --list-msgs070
pylint --list-msgs74
pylint --list-msgs75
Tránh sử dụng toán tử
pylint --list-msgs070 và
pylint --list-msgs312 để tích chuỗi trong 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à
pylint --list-msgs313 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
pylint --list-msgs314. 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
pylint --list-msgs76
pylint --list-msgs77
Hã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
pylint --list-msgs315 hoặc
pylint --list-msgs316 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
pylint --list-msgs78
pylint --list-msgs79
Thích
pylint --list-msgs090 cho chuỗi nhiều dòng hơn là
pylint --list-msgs318. Các dự án có thể chọn sử dụng
pylint --list-msgs318 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
pylint --list-msgs315 cho các chuỗi thông thường. Docstrings phải sử dụng
pylint --list-msgs090 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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin00
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin01
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin02
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin03
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin04
3. 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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin05
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin06
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin07
3. 10. 2 thông báo lỗi
Thô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ư
pylint --list-msgs70 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
Thông báo cần khớp chính xác với tình trạng lỗi thực tế
Các phần được nội suy cần phải luôn được xác định rõ ràng như vậy
Chúng nên cho phép xử lý tự động đơn giản [e. g. mò mẫm]
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin08
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin09
3. 11 Tệp, Ổ cắm và Tài nguyên có trạng thái tương tự
Đóng các tệp và ổ cắm một cách rõ ràng khi hoàn thành với chúng. Quy tắc này tự nhiên mở rộng cho các tài nguyên có thể đóng sử dụng ổ cắm bên trong, chẳng hạn như kết nối cơ sở dữ liệu và cả các tài nguyên khác cần được đóng theo cách tương tự. Chỉ kể tên một vài ví dụ, điều này cũng bao gồm ánh xạ mmap, đối tượng Tệp h5py và matplotlib. cửa sổ hình pyplot
Để các tệp, ổ cắm hoặc các đối tượng trạng thái khác mở một cách không cần thiết có nhiều nhược điểm
- Chúng có thể tiêu tốn tài nguyên hệ thống hạn chế, chẳng hạn như bộ mô tả tệp. Mã xử lý nhiều đối tượng như vậy có thể làm cạn kiệt các tài nguyên đó một cách không cần thiết nếu chúng không được trả lại hệ thống ngay sau khi sử dụng
- Việc giữ các tệp đang mở có thể ngăn các hành động khác như di chuyển hoặc xóa chúng hoặc ngắt kết nối hệ thống tệp
- Các tệp và ổ cắm được chia sẻ trong toàn bộ chương trình có thể vô tình được đọc từ hoặc ghi vào sau khi đóng một cách hợp lý. Nếu chúng thực sự bị đóng, các nỗ lực đọc hoặc ghi từ chúng sẽ đưa ra các ngoại lệ, làm cho vấn đề được biết đến sớm hơn
Hơn nữa, trong khi các tệp và ổ cắm [và một số tài nguyên hoạt động tương tự] tự động đóng khi đối tượng bị hủy, thì việc ghép thời gian tồn tại của đối tượng với trạng thái của tài nguyên là một cách làm kém.
- Không có gì đảm bảo khi nào bộ thực thi sẽ thực sự gọi phương thức
pylint --list-msgs
049. Các triển khai Python khác nhau sử dụng các kỹ thuật quản lý bộ nhớ khác nhau, chẳng hạn như bộ sưu tập rác bị trì hoãn, điều này có thể làm tăng thời gian tồn tại của đối tượng một cách tùy ý và vô thời hạn - Các tham chiếu không mong muốn đến tệp, e. g. trong toàn cầu hoặc theo dõi ngoại lệ, có thể giữ nó lâu hơn dự định
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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin80
Đối với các đối tượng giống như tệp không hỗ trợ câu lệnh
pylint --list-msgs058, hãy sử dụng
pylint --list-msgs327
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin81
Trong 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
3. 12 Ý kiến CẦN LÀM
Sử dụng nhận xét
pylint --list-msgs328 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ảo
Nhận xét
pylint --list-msgs328 bắt đầu bằng từ
pylint --list-msgs328 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ư
pylint --list-msgs331 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 bối cảnh theo thời gian.
pylint --list-msgs328 được theo sau bởi một lời giải thích về những việc phải làm
Mục đích để có định dạng
pylint --list-msgs328 nhất quán có thể search tìm hiểu để biết thêm chi tiết.
pylint --list-msgs328 không phải là cam kết rằng người được giới thiệu sẽ khắc phục sự cố. Vì vậy, khi bạn tạo một
pylint --list-msgs328 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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin82
Nếu
pylint --list-msgs328 của bạn ở 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 rất 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ểu
3. 13 Nhập định dạng
Nhập khẩu nên được trên các dòng riêng biệt;
E. g
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin83
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin84
Cá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
Báo cáo nhập khẩu trong tương lai của Python. Ví dụ
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
85Xem để biết thêm thông tin về những
Nhập thư viện chuẩn Python. Ví dụ
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
86nhập mô-đun hoặc gói của bên thứ ba. Ví dụ
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
87Nhập gói con kho lưu trữ mã. Ví dụ
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
88không dùng nữa. nhập dành riêng cho ứng dụng là một phần của gói con cấp cao nhất giống như tệp này. Ví dụ
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
89Bạn có thể tìm thấy mã Google Python Style cũ hơn để thực hiện việc này, nhưng nó không còn cần thiết nữa. Mã mới được khuyến khích không bận tâm với điều này. Đơn giản chỉ cần xử lý các lần nhập gói phụ dành riêng cho ứng dụng giống như các lần nhập gói phụ khác
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 [_______1339 trong ____1340]. Mã có thể tùy chọn đặt một dòng trống giữa các phần nhập
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin90
3. 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
pylint --list-msgs79/
pylint --list-msgs80 vì cả
pylint --list-msgs79 và
pylint --list-msgs80 đều không thể nằm trên cùng một dòng và bạn chỉ có thể làm như vậy với
pylint --list-msgs345 nếu không có
pylint --list-msgs346
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin91
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin92
3. 15 Getters và Setters
Các hàm getter và setter [còn được gọi là bộ truy cập và bộ biến đổi] nên được sử dụng khi chúng cung cấp vai trò hoặc hành vi có ý nghĩa để nhận hoặc đặt giá trị của biến
Đặc biệt, chúng nên được sử dụng khi nhận hoặc thiết lập biến phức tạp hoặc chi phí đáng kể, hiện tại hoặc trong tương lai hợp lý
Ví dụ: nếu một cặp getters/setters chỉ đọc và ghi một thuộc tính nội bộ, thì thuộc tính nội bộ sẽ được công khai thay thế. Để so sánh, nếu việc đặt một biến có nghĩa là một số trạng thái bị vô hiệu hóa hoặc được xây dựng lại, thì đó phải là một hàm setter. Lời gọi hàm gợi ý rằng một hoạt động có khả năng không tầm thường đang xảy ra. Ngoài ra, có thể là một tùy chọn khi cần logic đơn giản hoặc tái cấu trúc để không còn cần getters và setters nữa
Getters và setters nên tuân theo các hướng dẫn, chẳng hạn như
pylint --list-msgs347 và
pylint --list-msgs348
Nế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
pylint --list-msgs349,
pylint --list-msgs350,
pylint --list-msgs351,
pylint --list-msgs352,
pylint --list-msgs353,
pylint --list-msgs354,
pylint --list-msgs355,
pylint --list-msgs356,
pylint --list-msgs357,
pylint --list-msgs358,
pylint --list-msgs359,
pylint --list-msgs360,
pylint --list-msgs361
Tê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
pylint --list-msgs083. Không bao giờ sử dụng dấu gạch ngang
3. 16. 1 Tên cần tránh
tên ký tự đơn, ngoại trừ các trường hợp được phép cụ thể
- bộ đếm hoặc bộ lặp [e. g.
pylint --list-msgs
363,pylint --list-msgs
364,pylint --list-msgs
365,pylint --list-msgs
366, v.v. ] pylint --list-msgs
367 như một định danh ngoại lệ trong câu lệnhpylint --list-msgs
368pylint --list-msgs
369 dưới dạng xử lý tệp trong câu lệnhpylint --list-msgs
058- riêng tư không có ràng buộc [e. g.
pylint --list-msgs
372,pylint --list-msgs
373,pylint --list-msgs
374]
Xin lưu ý không lạm dụng đặt tên một ký tự. Nói chung, tính mô tả phải tỷ lệ thuận với phạm vi hiển thị của tên. Ví dụ:
pylint --list-msgs
363 có thể là một tên hay cho khối mã 5 dòng nhưng trong nhiều phạm vi lồng nhau, nó có thể quá mơ hồ- bộ đếm hoặc bộ lặp [e. g.
dấu gạch ngang [
pylint --list-msgs
071] trong bất kỳ tên gói/mô-đun nàopylint --list-msgs
377 tên [được đặt trước bởi Python]điều khoản xúc phạm
những tên không cần thiết bao gồm loại biến [ví dụ:.
pylint --list-msgs
378]
3. 16. 2 Quy ước đặt tên
"Nội bộ" có nghĩa là nội bộ của một mô-đun hoặc được bảo vệ hoặc riêng tư trong một lớp
Đặt trước một dấu gạch dưới [
pylint --list-msgs
41] có một số hỗ trợ để bảo vệ các biến và chức năng của mô-đun [linters sẽ gắn cờ quyền truy cập của thành viên được bảo vệ]Việc thêm trước một dấu gạch dưới kép [
pylint --list-msgs
380 hay còn gọi là "dunder"] vào một biến thể hiện hoặc phương thức sẽ làm cho biến hoặc phương thức đó trở nên riêng tư đối với lớp của nó [sử dụng xáo trộn tên]; . Thích một dấu gạch dướiĐặt các lớp liên quan và các chức năng cấp cao nhất cùng nhau trong một mô-đun. Không giống như Java, không cần giới hạn bản thân trong một lớp cho mỗi mô-đun
Sử dụng CapWords cho tên lớp, nhưng Lower_with_under. py cho tên mô-đun. Mặc dù có một số mô-đun cũ có tên là CapWords. py, điều này hiện không được khuyến khích vì thật khó hiểu khi mô-đun được đặt tên theo một lớp. ["chờ đã -- tôi đã viết
pylint --list-msgs
381 haypylint --list-msgs
382?"]Dấu gạch dưới có thể xuất hiện trong các tên phương thức kém nhất bắt đầu bằng
pylint --list-msgs
383 để phân tách các thành phần logic của tên, ngay cả khi các thành phần đó sử dụng CapWords. Một mẫu có thể làpylint --list-msgs
384; . Không có một cách chính xác nào để đặt tên cho các phương pháp thử nghiệm
3. 16. 3 Đặt tên tệp
Tên tệp Python phải có phần mở rộng là
pylint --list-msgs083 và không được chứa dấu gạch ngang [
pylint --list-msgs071]. Điều này cho phép chúng được nhập và kiểm tra. Nếu bạn muốn có thể truy cập tệp thực thi 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
pylint --list-msgs388
3. 16. 4 Nguyên tắc bắt nguồn từ Khuyến nghị của Guido
TypePublicInternalPackagespylint --list-msgs389Modules
pylint --list-msgs389
pylint --list-msgs391Classes
pylint --list-msgs392
pylint --list-msgs393Exceptions
pylint --list-msgs392Functions
pylint --list-msgs395
pylint --list-msgs396Global/Class Constants
pylint --list-msgs397
pylint --list-msgs398Global/Class Variables
pylint --list-msgs389
pylint --list-msgs391Instance Variables
pylint --list-msgs389
pylint --list-msgs391 [protected]Method Names
pylint --list-msgs395
pylint --list-msgs396 [protected]Function/Method Parameters
pylint --list-msgs389Local Variables
pylint --list-msgs389
3. 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 sử dụng
pylint --list-msgs407 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ơn
3. 17 chính
Trong Python,
pylint --list-msgs041 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
pylint --list-msgs409 và mã của bạn phải luôn kiểm tra
pylint --list-msgs410 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ập
Khi sử dụng absl, hãy sử dụng
pylint --list-msgs411
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin93
Nếu không, hãy sử dụng
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin94
Tấ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 nên thực hiện khi tệp đang được
pylint --list-msgs041ed
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 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ại
3. 19. 1 Quy tắc chung
Làm quen với PEP-484
Trong các phương thức, chỉ chú thích
pylint --list-msgs
89 hoặcpylint --list-msgs
90 nếu cần thiết cho thông tin loại phù hợp. e. g. ,dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin
95Tương tự, đừng cảm thấy bắt buộc phải chú thích giá trị trả về của
pylint --list-msgs
415 [trong đópylint --list-msgs
014 là tùy chọn hợp lệ duy nhất]Nếu bất kỳ biến nào khác hoặc kiểu trả về không được biểu thị, hãy sử dụng
pylint --list-msgs
417Bạ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 hãy chú thích các API công khai của bạn
- Sử dụng phán đoán để đạt được sự cân bằng tốt giữa một mặt là an toàn và rõ ràng, mặt khác là linh hoạt
- Chú thích mã dễ bị lỗi liên quan đến loại [lỗi trước đó hoặc độ phức tạp]
- Chú thích mã khó hiểu
- Chú thích mã khi 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 tính linh hoạt
3. 19. Ngắt 2 dòng
Cố 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ột tham số trên mỗi dòng". Để đả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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin96
Luô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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin97
Nế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
pylint --list-msgs066
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin98
Tù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
dict = 'something awful' # Bad Idea.. pylint: disable=redefined-builtin99
pylint --list-msgs31 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
pylint --list-msgs00
Như 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]
pylint --list-msgs01
Nế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
pylint --list-msgs02
pylint --list-msgs03
3. 19. 3 Tuyên bố chuyển tiếp
Nế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ã
pylint --list-msgs04
pylint --list-msgs05
3. 19. 4 giá trị mặc định
Theo , chỉ sử dụng khoảng trắng xung quanh
pylint --list-msgs067 cho các đối số có cả chú thích loại và giá trị mặc định
pylint --list-msgs06
pylint --list-msgs07
3. 19. 5 Không có Loại
Trong hệ thống loại Python,
pylint --list-msgs422 là loại "hạng nhất" và vì mục đích đánh máy,
pylint --list-msgs014 là bí danh của
pylint --list-msgs422. Nếu một đối số có thể là
pylint --list-msgs014, thì nó phải được khai báo. Bạn có thể sử dụng
pylint --list-msgs426, nhưng nếu chỉ có một loại khác, hãy sử dụng
pylint --list-msgs427
Sử dụng rõ ràng
pylint --list-msgs427 thay vì ngầm ẩn
pylint --list-msgs427. Các phiên bản trước của PEP 484 cho phép hiểu
pylint --list-msgs430 là
pylint --list-msgs431, nhưng đó không còn là hành vi ưa thích nữa
pylint --list-msgs08
pylint --list-msgs09
3. 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 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
pylint --list-msgs10
Cá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 tính năng kiểm tra loại trên một dòng bằng nhận xét đặc biệt
pylint --list-msgs432
pylint --list-msgs433 có tùy chọn tắt đối với các lỗi cụ thể [tương tự như lint]
pylint --list-msgs11
3. 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 một phép gán được chú thích - sử dụng dấu hai chấm và nhập giữa tên và giá trị của 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]
pylint --list-msgs12
. Mặ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
pylint --list-msgs434 ở cuối dòng
pylint --list-msgs13
3. 19. 9 Tuples vs Danh sách
Danh 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
pylint --list-msgs14
3. 19. 10 LoạiVars
Hệ thống kiểu Python có. Chức năng nhà máy
pylint --list-msgs371 là một cách phổ biến để sử dụng chúng
Ví dụ
pylint --list-msgs15
Một TypeVar có thể bị ràng buộc
pylint --list-msgs16
Biến loại được xác định trước phổ biến trong mô-đun
pylint --list-msgs61 là
pylint --list-msgs437. Sử dụng nó cho nhiều chú thích có thể là
pylint --list-msgs438 hoặc
pylint --list-msgs439 và tất cả phải cùng loại
pylint --list-msgs17
TypeVar phải có tên mô tả, trừ khi nó đáp ứng tất cả các tiêu chí sau
- không thể nhìn thấy bên ngoài
- không bị hạn chế
pylint --list-msgs18
pylint --list-msgs19
3. 19. 11 loại Chuỗi
Không sử dụng
pylint --list-msgs440 trong mã mới. Nó chỉ dành cho khả năng tương thích Python 2/3
Sử dụng
pylint --list-msgs439 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
pylint --list-msgs438
pylint --list-msgs20
Nế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ừ mô-đun
pylint --list-msgs61 và
pylint --list-msgs62 đượ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ừ mô-đun
pylint --list-msgs61 và
pylint --list-msgs62. Bán tại
pylint --list-msgs21
Cho rằng cách nhập này sẽ thêm các mục vào không gian tên cục bộ, các tên trong
pylint --list-msgs61 hoặc
pylint --list-msgs62 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
pylint --list-msgs449
pylint --list-msgs22
Ư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
pylint --list-msgs23
GHI CHÚ. Người dùng Apache Beam nên tiếp tục nhập vùng chứa tham số từ
pylint --list-msgs61
pylint --list-msgs24
3. 19. 13 Nhập khẩu có điều kiện
Chỉ 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 khối
pylint --list-msgs451
- Các loại được nhập có điều kiện cần được tham chiếu dưới dạng chuỗi, để tương thích chuyển tiếp với Python 3. 6 nơi 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 duy nhất để nhập mới được xác định ở đây; . Nếu không, đó sẽ là 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 ở ngay sau tất cả các lần nhập bình thường
- Không được có dòng trống nào trong danh sách nhập nhập
- Sắp xếp danh sách này như thể nó là một danh sách nhập thông thường
pylint --list-msgs25
3. 19. 14 phụ thuộc tuần hoàn
Cá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
pylint --list-msgs417. Đặ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
pylint --list-msgs26
3. 19. 15 thuốc gốc
Khi chú thích, ưu tiên chỉ định tham số loại cho các loại chung;
pylint --list-msgs27
pylint --list-msgs28
Nếu tham số loại tốt nhất cho một tên chung là
pylint --list-msgs417, 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
pylint --list-msgs29
pylint --list-msgs30
4 Lời Chia Tay
HÃ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