Bỏ qua

Hướng dẫn phong cách lập trình

Hướng dẫn này bao gồm thông tin và các nguyên tắc hướng dẫn về việc viết mã cho BeeWare Docs Tools.

Phong cách viết mã

BeeWare tuân thủ PEP 8 trong cơ sở mã của chúng tôi, ngoại trừ việc độ dài dòng được mở rộng từ 79 lên 88 ký tự. Chúng tôi sử dụng Ruff để áp dụng các quy ước PEP 8 khi có thể. Khi bạn commit mã nguồn, pre-commit sẽ chạy các kiểm tra, bao gồm cả Ruff. Khi có thể, công cụ này sẽ tự động định dạng mã nguồn của bạn để đảm bảo tuân thủ các tiêu chuẩn định dạng và phong cách của chúng tôi. Bạn có thể cấu hình một số IDE để tự động chạy Ruff khi lưu, điều này có thể hỗ trợ quá trình này.

Hãy nhớ rằng phần quan trọng nhất của PEP 8 là Mục 0: Sự nhất quán một cách mù quáng là ác quỷ của những bộ óc thiển cận. Có những tình huống mà việc tuân thủ tuyệt đối PEP 8 là không hợp lý, và điều quan trọng là phải hiểu rằng, khi cần thiết, việc viết mã không tuân theo các quy tắc được liệt kê là hoàn toàn chấp nhận được, và đôi khi thậm chí còn được khuyến khích. Biết khi nào nên không nhất quán với các quy tắc đó cũng quan trọng không kém việc duy trì tính nhất quán trong hầu hết các tình huống.

Một biểu hiện của điều này có thể thấy rõ qua các quy ước đặt tên. Các thư viện BeeWare thường phải kết nối với các ngôn ngữ khác. Khi xây dựng các lớp bọc (wrapper) cho các ngôn ngữ khác, việc tuân theo quy ước đặt tên của ngôn ngữ đích là điều nên làm (và trong một số trường hợp, là bắt buộc), thay vì tuân theo quy ước của Python. Ví dụ, khi gọi hoặc tham chiếu đến mã Java, các hàm nên tuân theo quy ước sử dụng dấu ngoặc nhọn mixedCase của Java, thay vì quy ước snake_case theo PEP 8.

Chúng tôi tuân thủ quy tắc chính tả của Hoa Kỳ trong việc đặt tên API, biến, v.v.

Ngoài ra, còn có một số bổ sung dành riêng cho BeeWare trong PEP 8:

Mặc dù việc chú thích kiểu tuân theo PEP 484 là tùy chọn, nhưng vẫn được khuyến khích mạnh mẽ, đặc biệt là đối với các giao diện API công khai.

Dưới đây là một ví dụ về định nghĩa hàm tiêu chuẩn kèm theo các gợi ý kiểu dữ liệu phù hợp và chuỗi tài liệu Sphinx:

def function_name(param1: int, param2: str) -> bool:
"""Ví dụ về hàm có kiểu dữ liệu và chuỗi tài liệu.

:param param1: Tham số đầu tiên.
:param param2: Tham số thứ hai.

:returns: Giá trị trả về. True nếu thành công, False nếu không.
"""

Chia nhỏ các lệnh gọi hàm dài

Khi một lệnh gọi hàm có nhiều hơn một đối số không thể nằm gọn trong một dòng, hãy đặt mỗi đối số vào một dòng riêng biệt và thêm dấu phẩy ở cuối dòng chứa đối số cuối cùng. Ruff cho phép (và sẽ đề xuất) cách trình bày nhiều đối số trên cùng một dòng được xuống dòng:

my_function(
    arg1, arg2, arg3
)

Không nên sử dụng kiểu này. Thay vào đó, hãy chia các đối số ra mỗi dòng một bằng cách thêm dấu phẩy ở cuối đối số cuối cùng:

my_function(
    arg1,
    arg2,
    arg3,
)

Chia chuỗi dài

Khi một đối số chuỗi phải được chia thành nhiều dòng để đáp ứng yêu cầu về độ dài dòng, hãy đặt các hằng số chuỗi được nối lại với nhau vào trong dấu ngoặc đơn để cho thấy rõ rằng chuỗi đó là một đối số duy nhất. Nói cách khác, chúng tôi khuyến nghị:

my_function(
    (
 "đây là một chuỗi rất dài"
 "được chia thành hai dòng"
    ),
    second_argument,
)

trên:

my_function(
    "đây là một chuỗi rất dài "
    "được chia thành hai dòng",
    second_argument,
)

Những điều cần tránh

Chúng tôi cố gắng tránh sử dụng các mô-đun utils càng nhiều càng tốt, nhưng cũng hiểu rằng đôi khi việc này là không thể tránh khỏi. Giải pháp thay thế được ưu tiên là tìm một vị trí khác trong mã nguồn để đặt tính năng đó, thay vì sử dụng mô-đun utils.

Theo nguyên tắc chung, chúng tôi cố gắng tránh hoặc hoãn việc thực thi bất kỳ đoạn mã khởi tạo nào tốn nhiều tài nguyên, nhằm giúp ứng dụng khởi động nhanh hơn. Ví dụ, các mô-đun trong gói toga-core được "tải chậm" — chúng chỉ được nhập khi có yêu cầu, thay vì được tải sẵn từ đầu. Điều này giúp tăng tốc độ khởi động và chỉ dành thời gian cho những thành phần mà ứng dụng thực sự đang sử dụng.

Khi viết bình luận, hãy tránh sử dụng các đại từ số nhiều ngôi thứ nhất như "chúng tôi" (ví dụ: hãy viết "Lặp qua" thay vì "Chúng tôi lặp qua").

Trong các chuỗi mô tả bài kiểm thử, hãy nêu rõ hành vi mong đợi mà mỗi bài kiểm thử thể hiện. Không nên thêm các cụm từ mở đầu như "Kiểm tra xem" hoặc "Đảm bảo rằng".

Hãy lưu lại mã số vé cho các vấn đề phức tạp, trong đó vé chứa các chi tiết bổ sung không thể mô tả một cách dễ dàng trong các chuỗi tài liệu (docstrings) hoặc bình luận. Hãy ghi số vé vào cuối câu như sau:

def test_foo():
 """Một chuỗi mô tả kiểm thử trông như thế này (#123456)."""