Khả năng đọc mã Python

Question

Tôi có trải nghiệm lập trình với các ngôn ngữ được nhập tĩnh. Bây giờ viết mã bằng Python Tôi cảm thấy khó khăn với khả năng đọc của nó. Hãy nói tôi có một lớp chủ:

class Host(object): 
    def __init__(self, name, network_interface): 
    self.name = name 
    self.network_interface = network_interface 

Tôi không hiểu từ định nghĩa này, những gì "network_interface" nên được. Đây có phải là một chuỗi , như "eth0" hoặc là một phiên bản của lớp NetworkInterface? Cách duy nhất tôi đang nghĩ đến để giải quyết vấn đề này là ghi lại mã bằng "docstring". Một cái gì đó như thế này:

class Host(object): 
    ''' Attributes: 
     @name: a string 
     @network_interface: an instance of class NetworkInterface''' 

Hoặc có thể có quy ước tên cho những thứ như thế không?

Answer 1

Sử dụng ngôn ngữ động sẽ dạy bạn điều gì đó về ngôn ngữ tĩnh: tất cả trợ giúp bạn nhận được từ ngôn ngữ tĩnh mà giờ đây bạn bỏ lỡ bằng ngôn ngữ động, không phải tất cả đều hữu ích.

Để sử dụng ví dụ của bạn, bằng ngôn ngữ tĩnh, bạn biết rằng tham số là một chuỗi và bằng Python bạn không sử dụng. Vì vậy, trong Python bạn viết một docstring.Và trong khi bạn đang viết nó, bạn nhận ra rằng bạn có nhiều điều để nói về nó hơn, "đó là một chuỗi". Bạn cần phải nói những gì dữ liệu trong chuỗi, và những gì định dạng nó cần phải có, và những gì mặc định là, và một cái gì đó về điều kiện lỗi.

Và sau đó bạn nhận ra rằng bạn nên viết tất cả những thứ đó xuống cho ngôn ngữ tĩnh của bạn. Chắc chắn, Java sẽ buộc bạn biết rằng đó là một chuỗi, nhưng có tất cả các chi tiết khác cần phải được chỉ định, và bạn phải tự làm điều đó làm việc trong bất kỳ ngôn ngữ.

Answer 2

Quy ước về chuỗi tài liệu là PEP 257.

Ví dụ có theo định dạng này cho các đối số quy định cụ thể, bạn có thể thêm các loại nếu họ có vấn đề:

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    Keyword arguments: 
    real -- the real part (default 0.0) 
    imag -- the imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

Cũng có một PEP từ chối cho docstrings cho các thuộc tính (chứ không phải là lập luận constructor).

Answer 3

Giải pháp pythonic nhất là ghi lại các ví dụ. Nếu có thể, hãy nêu rõ những hoạt động mà một đối tượng phải hỗ trợ để được chấp nhận, thay vì một loại cụ thể.

class Host(object): 
    def __init__(self, name, network_interface) 
    """Initialise host with given name and network_interface. 

    network_interface -- must support the same operations as NetworkInterface 

    >>> network_interface = NetworkInterface() 
    >>> host = Host("my_host", network_interface) 

    """ 
    ... 

Tại thời điểm này, hãy móc nguồn của bạn lên đến doctest để đảm bảo ví dụ về tài liệu của bạn tiếp tục hoạt động trong tương lai.

Answer 4

Cá nhân tôi thấy rất hữu ích khi sử dụng pylint để xác thực mã của tôi.

Nếu bạn làm theo đề nghị pylint gần như tự động mã của bạn trở nên dễ đọc hơn, bạn sẽ cải thiện kỹ năng viết python của bạn, tôn trọng quy ước đặt tên. Bạn cũng có thể xác định quy ước đặt tên của riêng bạn và cứ thế. Nó rất hữu ích đặc biệt cho một người mới bắt đầu python.

Tôi đề nghị bạn sử dụng.

Answer 5

Python, mặc dù không được công khai gõ như C hoặc Java, vẫn được nhập và sẽ ném ngoại lệ nếu bạn đang làm việc với các loại chỉ đơn giản là không chơi tốt đẹp với nhau.

Để kết thúc, nếu bạn lo ngại về mã của mình đang được sử dụng đúng, duy trì chính xác, v.v ... chỉ cần sử dụng docstrings, comments hoặc thậm chí các tên biến rõ ràng hơn để cho biết loại nên là gì.

Thậm chí tốt hơn, hãy bao gồm mã cho phép nó xử lý bất kỳ loại nào nó có thể được chuyển miễn là nó mang lại kết quả khả dụng.

Answer 6

Một lợi ích của việc nhập tĩnh là các loại là một dạng tài liệu. Khi lập trình bằng Python, bạn có thể tài liệu linh hoạt hơn và trôi chảy hơn. Tất nhiên trong ví dụ của bạn, bạn muốn nói rằng network_interface nên triển khai NetworkInterface, nhưng trong nhiều trường hợp, kiểu rõ ràng từ ngữ cảnh, tên biến, hoặc theo quy ước, và trong những trường hợp này bằng cách bỏ qua rõ ràng bạn có thể tạo ra mã dễ đọc hơn. Thông thường là để mô tả ý nghĩa của một tham số và ngầm đưa ra loại.

Ví dụ:

def Bar(foo, count): 
    """Bar the foo the given number of times.""" 
    ... 

này mô tả các chức năng ngắn gọn và chính xác. Những gì foo và bar có nghĩa là sẽ được rõ ràng từ bối cảnh, và số đó là một (dương) số nguyên là tiềm ẩn.

Ví dụ của bạn, tôi muốn đề cập đến chỉ loại trong chuỗi tài liệu:

"""Create a named host on the given NetworkInterface.""" 

Đây là ngắn hơn, dễ đọc hơn, và chứa hơn thông tin hơn một danh sách các loại.