Moja ściąga z PEP 8 – część 1

Układ kodu

Wcięcia:

• spacje na jeden poziom wcięcia

Spacje czy tabulatory:

• nigdy nie używa się jednocześnie spacji i tabulatorów jako wcięć w kodzie

Maksymalna długość linii:

• maksymalnie 79 znaków Preferuje się łamanie linii przez użycie implikowanej kontynuacji linii w nawiasach {}[](), w miarę potrzeby można dodać dodatkową parę nawiasów dookoła długiego wyrażenia. Należy zadbać o właściwe wcięcie kontynuowanej linii. Zaleca się łamać linię po operatorze binarnym, nie przed nim. Przykład:

      def __init__(self, width, height,
              color='black', emphasis=None, highlight=0):
          if width == 0 and height == 0 and \
                  color == 'red' and emphasis == 'strong' or \
                  highlight > 100:
                      raise ValueError("sorry, you lose")
                  if width == 0 and height == 0 and (color == 'red' or
                          emphasis is None):
                      raise ValueError("I don't think so -- values are %s, %s" %
                              (width, height))
                      Blob.__init__(self, width, height,
                              color, emphasis, highlight)

Puste linie:

• należy oddzielać definicje funkcji i klas na najwyższym poziomie dwiema liniami
• definicje metod w klasie są oddzielane przez jedną pustą linię
• używaj oszczędnie pustych linii do oddzielania logicznych sekcji w funkcji

Importy

• Importy zwykle umieszcza się w osobnych liniachDobrze:

        import os
        import sys

  Źle:

        import sys, os

  ale poniższe jest w porządku:

        from subprocess import Popen, PIPE

• Importy umieszcza się u góry pliku, bezpośrednio po komentarzu lub docstringu modułu i przed zmiennymi i stałymi modułuImport powinny być pogrupowane w następującej kolejności: 1. importy z biblioteki standardowej 2. zewnętrzne importy spoza aplikacji 3. import z lokalnej aplikacji/biblioteki

  Powinno się umieszczać pustą linię pomiędzy powyższymi trzema grupami importów

• Względne importy dla wewnątrz-pakietowych importów są bardzo odradzane, zawsze należy używać pełnej ścieżki pakietu dla wszystkich importów
• Podczas importu klas z modułu zawierającego klasy jest w porządku pisać:

        from myclass import MyClass
        from foo.bar.yourclass import YourClass

  lecz jeśli występuje konflikt nazw z lokalnymi klasami należy użyć:

        import myclass
        import foo.bar.yourclass

  i używa się „myclass.MyClass” oraz „foo.bar.yourclass.YourClass”

Odstępy w wyrażeniach i deklaracjach

• Dobre przykłady:

        spam(ham[1], {eggs: 2})
   
        if x == 4: print x, y; x, y = y, x
   
        spam(1)
   
        dict['key'] = list[index]
   
        x = 1
        y = 2
        long_variable = 3

• Pojedyncza spacja po każdej ze stron operatorów: (=), (+=, -= itp.), (==, <, >, !=, <>, <=, >=, in, not in, is, is not) i (and, or, not)
• Spacje dookoła operatorów arytmetycznych:

        i = i + 1
        submitted += 1
        x = x * 2 - 1
        hypot2 = x * x + y * y
        c = (a + b) * (a - b)

• brak spacji dookoła znaku = jeśli wskazuje on na domyślny parametr funkcji lub argument.

        def complex(real, imag=0.0):
            return magic(r=real, i=imag)

• wielokrotne instrukcje na tej samej linii są niewskazane:

        if foo == 'blah':
            do_blah_thing()
        do_one()
        do_two()
        do_three()

• raczej nie umieszczać instrukcji warunkowych na tej samej liniiRaczej nie:

        if foo == 'blah': do_blah_thing()
        for x in lst: total += x
        wile t < 10: t = delay()

  Absolutnie nie:

        if foo == 'blah': do_blah_thing()
        else: do_non_blah_thing()
   
        try: something()
        finally: cleanup()
   
        do_one(); do_two(); do_three(long, argument,
              list, like, this)
   
        if foo == 'blah': one(); two(); three()

Komentarze

• Należy bezwzględnie utrzymywać aktualne komentarze w kodzie. Nieaktualne lub wręcz mylące komentarze są gorsze niż ich brak.
• Komentarze powinny być pełnymi zdaniami. Komentarz który jest zdaniem lub frazą powinien mieć pierwsze słowo napisane wielkimi literami, chyba, że jest identyfikatorem rozpoczynającym się małą literą. Nie zmienia się przypadku identyfikatorów.(?)
• Kropka na końcu krótkiego komentarza może być pominięta. Blok komentarza na ogół składa się jednego lub więcej paragrafów składających się ze zdań zakończonych kropką.
• Należy używać dwóch spacji po kropce kończącej zdanie.
• Komentarze zawsze należy pisać po angielsku.

Bloki komentarzy.

• Bloki komentarzy dotyczą do części (lub całego) kodu, który po nich następuje i powinny mieć takie samo wcięcie jak ów kod. Każda linia kodu zaczyna się ze znaku # i spacji (# Komentarz do kodu.).
• Paragrafy wewnątrz komentarzy oddzielone są są linią zawierającą tylko jeden znak #.

Komentarze w linii z kodem

• Używać oszczędnie
• Powinny być oddzielone od instrukcji min. dwiema spacjami.
• Nie komentuje się instrukcji oczywistych, np.:

        x = x + 1               # increment x by 1

Teksty dokumentacji (Docstrings)

• Należy pisać docstringi dla publicznych modułów, funkcji, klas i metod. Docstringi nie są konieczne dla niepublicznych metod lecz powinno się pisać co dana metoda robi. Ten komentarz powinien następować po linii z def.
• PEP 257 opisuje poprawne konwencje stosowania docstringów. Przykład:

        """Return a foobang
   
        Optional plotz says to frobnicate the bizbaz first.
   
        """

• Dla docstringu w jednej lini:

        """Optional plotz says to frobnicate the bizbaz first."""

Version Bookkeeping (?)

Napisane na podstawie PEP 8 . Nie jestem profesjonalistą, ale staram się. Tekst jest pomocą przede wszystkim dla mnie. Jeśli komuś jeszcze będzie on pomocny ucieszę się. Jeszcze bardziej będę zadowolony jeśli ktoś doświadczony tu zajrzy i zechce skomentować to, i tamto.