Czytnik kodu Pythona

Question

Mam doświadczenie w programowaniu ze statycznie napisanymi językami. Pisząc kod w Pythonie, odczuwam trudności z jego czytelnością. Powiedzmy, że mam klasy Host:

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

nie rozumiem z tej definicji, co „network_interface” powinno być. Czy jest to ciąg , taki jak "eth0" lub czy jest to instancja klasy NetworkInterface? Jedynym sposobem na rozwiązanie tego problemu jest udokumentowanie kodu za pomocą "docstring". Coś takiego:

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

A może istnieją konwencje nazw takich rzeczy?

Answer 1

Używanie dynamicznych języków nauczy cię czegoś o statycznych językach: wszelkiej pomocy, którą uzyskałeś z języka statycznego, którego teraz brakuje w dynamicznym języku, nie było to wcale pomocne.

Aby użyć twojego przykładu, w języku statycznym, wiesz, że parametr był łańcuchem, aw Pythonie nie. Więc w Pythonie piszesz docstring.Pisząc, zdajesz sobie sprawę, że masz więcej do powiedzenia na ten temat, niż "to ciąg". Musisz powiedzieć, jakie dane znajdują się w ciągu znaków, jaki format powinien mieć i jakie są wartości domyślne, a także o warunkach błędu.

A potem zdajesz sobie sprawę, że powinieneś napisać to wszystko również dla swojego statycznego języka. Jasne, Java zmusiłaby cię do przekonania, że ​​jest to ciąg znaków, ale musisz podać wszystkie inne szczegóły i musisz ręcznie wykonać tę pracę w dowolnym języku.

Answer 2

Konwencje dotyczące docstrukcji znajdują się pod numerem PEP 257.

Przykład następuje ten format argumentów określających, można dodać typy jeśli znaczenia:

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 
    ... 

Był też odrzucony PEP dla docstrings dla atrybutów (zamiast argumentów konstruktora).

Answer 3

Najbardziej pythonicowym rozwiązaniem jest dokumentowanie przykładami. Jeśli to możliwe, określ, które operacje, które obiekt musi obsługiwać, aby były akceptowalne, zamiast określonego typu.

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) 

    """ 
    ... 

W tym momencie hak źródło do doctest aby upewnić się, że przykłady doc nadal pracować w przyszłości.

Answer 4

Osobiście znalazłem bardzo przydatny w użyciu pylint do sprawdzania poprawności mojego kodu.

Jeśli będziesz podążał za sugestią dotyczącą pylintu prawie automatycznie, twój kod stanie się bardziej czytelny, poprawisz swoje umiejętności pisania w języku Python, przestrzegając konwencji nazewnictwa. Możesz także zdefiniować własne konwencje nazewnictwa i tak dalej. Jest to bardzo przydatne szczególnie dla początkujących Pythona.

Proponuję użyć.

Answer 5

Python, choć nie tak jawnie napisany jak C lub Java, jest nadal pisany na maszynie i będzie generował wyjątki, jeśli robisz rzeczy z typami, które po prostu nie grają dobrze razem.

W tym celu, jeśli obawiasz się, że kod jest używany poprawnie, poprawnie konserwowany itp., Po prostu użyj docstrukcji, komentarzy lub nawet bardziej jawnych nazw zmiennych, aby wskazać, jaki powinien być typ.

Jeszcze lepiej, dołącz kod, który pozwoli mu obsłużyć dowolny typ, który może być przekazany, o ile daje użyteczny wynik.

Answer 6

Jedną z zalet statycznego pisania jest to, że typy są formą dokumentacji. Podczas programowania w Pythonie możesz dokumentować bardziej elastycznie i płynnie. Oczywiście w twoim przykładzie chciałbyś powiedzieć, że network_interface powinien implementować NetworkInterface, ale w wielu przypadkach typ jest oczywisty z kontekstu, nazwy zmiennej lub konwencji, aw tych przypadkach przez pominięcie oczywistego, że możesz wytworzyć bardziej czytelny kod. Wspólne jest opisanie znaczenia parametru i pośrednie podanie typu.

Na przykład

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

ten opisuje funkcję krótko i precyzyjnie. Znaczenie słowa "foo" i "bar" będzie oczywiste z kontekstu, a liczba ta jest liczbą całkowitą (dodatnią).

Na swoim przykładzie, ja tylko wspomnieć typ na ciąg dokumentu:

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

ten jest krótszy, bardziej czytelny i zawiera więcej informacji niż listą typów.