+1

A Best of the Best Practices Guide for Python

I. Style

1. Naming

  • Các tên biến, hàm, phương thức, packages, modules được đặt tên là chữ thường với dấu gạch dưới (lower_case):

    • lower_case_with_underscores
  • Classes and Exceptions được đặt tên theo kiểu viết hoa chữ cái đầu tiên của từ (UpperCase):

    • Marvel, ExampleController
  • Protected methods và internal functions bắt đầu với một dấu gạch dưới, chữ thường:

    • _example_function(variable, ...)
  • Private methods bắt đầu với hai dấu gạch dưới, chữ thường:

    • __example_function(variable, ...)
  • Constant:

    • ALL_CAPS_WITH_UNDERSCORES
  • Tránh các tên biến 1 chữ (đặc biệt là l, O, I). Ngoại lệ: Trong các đoạn ngắn, khi ý nghĩa của biến được hiển thị rõ ràng từ tình huống.

    for e in elements:
    e.mutate()
    
  • Tránh ghi nhãn thừa:

    Đúng:

    import audio
    core = audio.Core()
    controller = audio.Controller()
    

    Sai:

    import audio
    core = audio.AudioCore()
    controller = audio.AudioController()
    
  • Thích ký hiệu ngược:

    Đúng:

    elements = ...
    elements_active = ...
    elements_defunct = ...
    

    Sai:

    elements = ...
    active_elements = ...
    defunct_elements ...
    
  • Tránh các phương thức getter và setter:

    Đúng:

    person.age = 42
    

    Sai:

    person.set_age(42)
    
  • Indentation: Khoảng cách thụt lề luôn là 4 khoảng trắng không sử dụng tabs.

2. Imports:

  • Import toàn bộ modules thay vì các ký hiệu riêng lẻ trong 1 module

    Đúng:

    import canteen
    import canteen.sessions
    from canteen import sessions
    

    Sai:

    from canteen import get_user  # Symbol from canteen/__init__.py
    from canteen.sessions import get_session  # Symbol from canteen/sessions.py
    

    Ngoại lệ: Đối với mã của bên thứ ba nơi tài liệu nói rõ ràng để nhập các ký hiệu riêng lẻ.

  • Đặt tất cả các import ở đầu trang với ba phần, mỗi phần được phân tách bằng một dòng trống, theo thứ tự:

    1. System import
    2. Third-party imports
    3. Local source tree imports
    

    Điều này để làm rõ với mỗi module đến từ đâu

3. Documentation

  • Sử dụng tài liệu một dòng cho các chức năng rõ ràng:
    """Return the pathname of ``foo``."""
    
  • Tài liệu nhiều dòng nên bao gồm:
    • Tóm tắt
    • Các trường hợp sử dụng, nếu thích hợp
    • Luận điểm
    • Kiểu trả về và ý nghĩa, trừ trường hợp không trả về
    """Train a model to classify Foos and Bars.
    
    Usage::
    
        >>> import klassify
        >>> data = [("green", "foo"), ("orange", "bar")]
        >>> classifier = klassify.train(data)
    
    :param train_data: A list of tuples of the form ``(color, label)``.
    :rtype: A :class:`Classifier <Classifier>`
    """
    
  • Chú ý:
    • Sử dụng các từ hành động ("Return") thay vì mô tả ("Returns").
    • Sử dụng phương thức __init__ trong chuỗi tài liệu cho lớp.
    class Person(object):
    """A simple representation of a human being.
    
    :param name: A string, the person's name.
    :param age: An int, the person's age.
    """
    def __init__(self, name, age):
        self.name = name
        self.age = age
    

4. Comments

  • Sử dụng một cách tiết kiệm. Code dễ đọc tốt hơn là có nhiều comment. Thông thường, các phương thức gọn gàng, ngắn gọn có hiệu quả hơn comment.

    Sai:

    # If the sign is a stop sign
    if sign.color == 'red' and sign.sides == 8:
        stop()
    

    Đúng:

    def is_stop_sign(sign):
        return sign.color == 'red' and sign.sides == 8
    
    if is_stop_sign(sign):
        stop()
    
  • Khi bạn viết comment hãy nhớ áp dụng Strunk và White - PEP 8

5. Line Lengths

  • Don't stress over it. 80-100 characters is fine.
  • Sử dụng dấu ngoặc đơn cho dòng kế tiếp:
    wiki = (
        "The Colt Python is a .357 Magnum caliber revolver formerly manufactured "
        "by Colt's Manufacturing Company of Hartford, Connecticut. It is sometimes "
        'referred to as a "Combat Magnum". It was first introduced in 1955, the '
        "same year as Smith & Wesson's M29 .44 Magnum."
    )
    

II. Testing

  • Cố gắng cho phạm vi 100% code coverage, nhưng không bị ám ảnh về số % đó.

1. General testing guidelines

  • Sử dụng tên dài, mô tả. Điều này thường làm giảm sự cần thiết về doctrings trong các phương thức test.
  • Test nên được cô lập. Không tương tác với cơ sở dữ liệu hoặc network thật. Sử dụng một cơ sở dữ liệu thử nghiệm riêng biệt, hoặc sử dụng các mock objects.
  • Prefer factories to fixtures.
  • Không bao giờ để các test chưa hoàn thành pass, nếu không bạn sẽ có nguy cơ quên nó. Thay vào đó, thêm 1 placeholder giống như: assert False, "TODO: finish me".

2. Unit Tests

  • Tập trung vào từng phần nhỏ của một chức năng.
  • Nên chạy nhanh, nhưng kiểm tra chậm thì tốt hơn là không kiểm tra.
  • Nó thường có ý nghĩa để có một Class testcase cho một Class hoặc Model.
    import unittest
    import factories
    
    class PersonTest(unittest.TestCase):
        def setUp(self):
            self.person = factories.PersonFactory()
    
        def test_has_age_in_dog_years(self):
            self.assertEqual(self.person.dog_years, self.person.age / 7)
    

3. Functional Tests

Các functional tests là các test cấp cao hơn gần với cách người dùng cuối tương tác với ứng dụng. Chúng thường được sử dụng cho các ứng dụng web và GUI:

  • Viết các tests như kịch bản. Tên testcase và method test nên đọc giống như mô tả của kịch bản đó.
  • Sử dụng các bình luận viết ra các kịch bản, trước khi viết mã kiểm tra.
    import unittest
    
    class TestAUser(unittest.TestCase):
    
    def test_can_write_a_blog_post(self):
        # Goes to the her dashboard
        ...
        # Clicks "New Post"
        ...
        # Fills out the post form
        ...
        # Clicks "Submit"
        ...
        # Can see the new post
        ...
    

Lưu ý các testcase và method tests đọc cùng nhau như "Test A User can write a blog post".

Nguồn


All Rights Reserved

Viblo
Let's register a Viblo Account to get more interesting posts.