Programowanie

Tworzenie aplikacji rozszerzających funkcjonalność programu Subiekt GT Sfera

System sprzedaży Subiekt GT Sfera jest to zaawansowana aplikacja do obsługi sprzedaży. Posiada ogromne możliwości i bardzo dużą liczbę funkcjonalności. W połączeniu daje to system możliwy do wykorzystania w zupełnie różnych działach firmy, przez różnych ludzi, pełniących różne funkcje. Jednakże często dany użytkownik potrzebuje tylko korzystać z programu w bardzo ograniczonym zakresie, często w sposób rutynowy i powtarzalny. Kiedy zachodzi taka sytuacja można wykorzystać mechanizm umożliwiający napisanie aplikacji (programu) korzystającego z wewnętrznych funkcji subiekta i tylko tych funkcji, które są potrzebne w określonym miejscu w firmie i określonemu użytkownikowi bądź użytkownikom.

Stworzenie takiej aplikacji pozwala na:

  • uproszczenie interfejsu programu, co wpływa na łatwość obsługi i czas potrzebny do przeszkolenia użytkownika,
  • zmniejsza ryzyko popełnienia błędu przy wprowadzaniu danych przez wprowadzenie wszystkich rutynowych, powtarzalnych danych przez automat wbudowany w aplikację, a pozostawienie do wprowadzenia użytkownikowi tylko tych, które się zmieniają np. waga, kwota itp.

Aplikacja Subiekt GT Sfera jest to system sprzedaży, który oprócz widocznego okienkowego interfejsu użytkownika posiada jeszcze wewnętrzny (niewidoczny dla użytkownika) interfejs. Interfejs ten to mechanizm, który pozwala na wykonywanie operacji w aplikacji Subiekt GT Sfera przez inne programy. Ujmując to inaczej – do wykonywania operacji, które normalnie wykonuje operator programu przy pomocy myszki i klawiatury można użyć odpowiednio napisanej aplikacji, która wszystkie bądź większość tych operacji wykona automatycznie – dużo szybciej i z mniejszym prawdopodobieństwem popełnienia błędu.

Sposobność do skorzystania z wyżej opisanych możliwości pojawia się kiedy:

– pojawia się uzasadniona potrzeba wprowadzenia dużej ilości danych do systemu Subiekt pochodzących z innych źródeł,

– zgromadzone w systemie dane są wykorzystywane przez inny system przetwarzający te dane,

– zaistnieje potrzeba uproszczenia pracochłonnych i powtarzalnych operacji wykonywanych w systemie Subiekt,

– należy zminimalizować użytkownikom dostęp do operacji wykonywanych w systemie jedynie do tych niezbędnych, potrzebnych do wykonania ściśle określonych zadań.

– należy odczytać i wprowadzić dane zakodowane (np. dane zakodowane kodem kreskowym GS1-128)
Każda z powyższych sytuacji skłania do zastanowienia się nad rozwiązaniem problemu. Przy pomocy aplikacji współpracującej z systemem Subiekt można pomóc rozwiązać powyższe zagadnienia. Wpierw jednak należy się zastanowić czy i jakie rozwiązania przyniosą największe korzyści.

Korzyści jakie są możliwe do osiągnięcia przez skorzystanie z możliwości systemu Subiekt GT Sfera można zebrać w kilku punktach:

oszczędność czasu potrzebnego na wykonywanie operacji w systemie (wystawiania dokumentów, aktualizacji danych o produktach, tworzenia zestawień i raportów),

zminimalizowanie możliwości niepoprawnego wprowadzenia danych bądź zupełne wyeliminowanie pomyłek,

– oszczędność zasobów wymaganych do wyszkolenia użytkownika do obsługi systemu Subiekt GT na rzecz zapoznania się jego jedynie z aplikacją o prostym, mało złożonym interfejsie – szybkie wdrożenie użytkownika do pracy z systemem

dostosowanie do procedur obowiązujących w organizacji do wdrożonego weń systemu.

Klawiatura – ważny wybór nie tylko dla programisty

Klawiatura komputerowa – jak ważny jest to element komputer nie trzeba chyba wspominać. Klawiatura służy do interakcji z komputerem – do pisania tekstów, wydawania poleceń, obsługi programów oraz pisania kodu programów komputerowych. Element bagatelizowany przez większość kupujących zestawy komputerowe stacjonarne i przenośne (laptopy). Być może dlatego, że klawiatura jest jednym z najtańszych elementów komputera i wydając nań pieniądze nie rozważa się zbytnio nad wyborem marki i modelu tego elementu. Tymczasem wybór klawiatury jest jednym z najważniejszych wyborów przy zakupie komputera, szczególnie dla osób, dla których jest on narzędziem pracy lub pomocą w oddawaniu się własnemu hobby.

Wyobraźmy sobie, że kupujemy łóżko. Nie bierzemy pierwszego lepszego lecz takie, które będzie wygodą i funkcjonalnością najbardziej odpowiadać naszym potrzebom. Może to być wersalka jeśli będzie służyć także do siedzenia lub materac jeśli powinna być możliwość szybkiego i częstego zwolnienia miejsca. Do sypialni wybierzemy łóżko, które będzie wygodnie do spania i figlowania. Wybór nie jest łatwy.

Klawiatura jest jednym z elementów, który ma stały kontakt z ludzkim ciałem – najczęściej z rękami, choć są osoby, które używają klawiatury posługując się stopami. Urządzenie powinno być wygodne, klawisze dobrze wyczuwalne pod palcami, opisane w sposób trwały, odporny na ścieranie, a od naciskania klawiszy nie powinny boleć palce. Skok klawisza powinien być odpowiedni, nie za twardy, ale wyraźny, nie wymagający zbyt dużej siły, ale na tyle oporny aby nie wysyłać znaku do komputera przez byle muśnięcie klawisza.

Po dość długim okresie wybierania, analizowania, przymierzania się mój wybór padł na bardzo prostą klawiaturę marki Logitech – Keyboard K120 For Business. Jest to model niedrogi, ale bardzo przypadł mi do gustu. Tak oto wygląda:

Klawiatura Keyboard K120 PN: 920-002479

Standardowy układ klawiszy US Ansi. Należy zwrócić uwagę na kod producenta 920-002479. Tę klawiaturę producent pakuje w szare, kartonowe pudełko. Taki sam model lecz z innym układem klawiszy jest również sprzedawany w Polsce – jego oznaczenie to 920-002509 i jest dostępny w kolorowych, kartonowych opakowaniach. Wygląda podobnie jak na zdjęciu poniżej:

Fizyczny układ klawiszy jest taki jak na zdjęciu, lecz klawisze są inaczej opisane. Przy zakupie klawiatur marki Logitech trzeba zwrócić baczną uwagę na dokładny typ i pytać się bez ogródek o układ klawiszy jaki nas interesuje. Zdjęcia na opakowaniach produktów nie odpowiadają ich rzeczywistej zawartości, dlatego należy się upewnić co kupujemy aby potem nie rozpakować klawiatury, która ma nieodpowiadający nam układ klawiszy. Nie należy się zbytnio też sugerować zawartością zdjęć na stronie producenta. Zdjęcia klawiatur są orientacyjne i takie same dla wszystkich układów we wszystkich krajach, w których są sprzedawane

Używam modelu K120 już ponad tydzień i praca przy komputerze jest dla mnie dużo przyjemniejsza niż z poprzednią klawiaturą. Mogę z powodzeniem polecić ten produkt każdemu, kto szuka wygodnej, dobrej klawiatury bez dodatkowych, często prawie nieużywanych tzw. klawiszy multimedialnych. Dodam, że model „For Business” jest tańszy, podejrzewam, że ze względu na surowe, bezbarwne, kartonowe opakowanie.

Dodatkowe informacje o klawiaturach.

Klawiatury dzielą się ogólnie na mechaniczne – drogie i z tego powodu dosyć rzadko oferowane oraz tanie membranowe, „kopułkowo-gumowe”, z piankowych elementów oraz  inne konstrukcje. Obszerny artykuł na temat budowy różnych typów klawiatur zapewne wyjaśni dociekliwym czytelnikom tajniki ich budowy oraz zalety i wady. Warto także przejrzeć artykuł o układach klawiatur aby móc trochę pozaginać sprzedawców.  😉

Na koniec artykuł z przymrużeniem oka o dziesięciu najgorszych klawiaturach wszech czasów.

By grzeszy on Listopad 18, 2010 | Opinie, Programowanie, Sprzęt | 1 comment
Tagi: , , ,

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

Zalecenia programistyczne:

  • Kod powinien być pisany w sposób, który nie powoduje problemów w innych implementacjach Pythona (PyPy, Jython, IronPython, Pyrex, Psyco i innych)

    Dla przykładu nie należy polegać na implementacji łączenia ciągów „w miejscu” (in-place) w formie a+=b lub a=a+b. Takie deklaracje wykonują się dużo wolniej w Jython. W częściach biblioteki gdzie wydajność jest szczególnie ważna w zamian powinna być użyta konstrukcja ”.join(). Taka konstrukcja daje pewność, że połączenie zdarzy się liniowo w czasie pośród różnych implementacji.

  • Porównania do singletonów takich jak None zawsze powinno być robione przy pomocy is lub is not, nigdy operatorów porównania.

    Wystrzegać należy się pisania if x kiedy ma się na myśli if x is not None — np. kiedy testuje się czy danej zmiennej czy argumentowi, który domyślnie przyjmuje wartość None została przypisana inna wartość. Inne wartości mogą mieć taki typ (tak jak kontener), że jest on fałszywy w kontekście booleanowskim (?).

  • Używać klas wyjątków w Pythonie (class-based exceptions)

    Wyjątki typu string w nowym kodzie są zabronione, ponieważ ta właściwość języka zostanie usunięta w Pythonie 2.6.

    Moduły i pakiety (packages) powinny definiować własne specyficzne dla siebie klasy wyjątków (exception class), które powinny dziedziczyć z wbudowanej (built-in) klasy wyjątków. Zawsze należy zawierać docstringa klasy.

    Mają tutaj również zastosowanie konwencje nazewnictwa klas, chociaż powinno dodawać się sufiks Error do nazwy klasy wyjątku, jeśli wyjątek jest błędem. Wyjątki „nie-błędy” nie potrzebuję specjalnego sufiksu.

          class MessageError(Exception):
              """Base class for errors in the email package."""
  • Kiedy podnosi się wyjątek należy używać raise ValueError(‚message’) zamiast starszej formy raise ValueError, ‚message’.

    Forma z nawiasami jest preferowana, ponieważ kiedy argumenty wyjątku są długie lub zawierają formatowanie ciągów nie zachodzi potrzeba używania znaku kontynuacji linii dzięki otoczeniu nawiasami. Starsza forma będzie niedostępna w Pythonie 3000.

  • Podczas przechwytywania wyjątków, należy podać jaki wyjątek się przechwytuje kiedykolwiek to jest możliwe, zamiast używać „czystej” klauzuli except.

    Na przykład:

          try:
              import platform_specific_module
          except ImportError:
              platform_specific_module = None

    Samotna klauzula except przechwyci także wyjątki SystemExit i KeyboardInterrupt, co uczyni trudniejszym przerwanie działania programu przy pomocy i przesłoni inne, nieprzewidziane problemy. W przypadku potrzeby łapania wszystkich wyjątków, które sygnalizują błędy w programie należy używać except Exception

    Dobrą zasadą jest ograniczyć użycie czystego except do dwóch przypadków:

    • Jeśli uchwyt (?) wyjątku będzie drukował log ze śledzenia błędu (traceback), przynajmniej użytkownik będzie świadom, że wystąpił błąd.
    • Jeśli kod wymaga wyczyszczenia, lecz wtedy pozwala wyjątkowi propagować się w górę z raise (?). W takim wypadku try…finally jest lepszym sposobem aby obsłużyć wyjątek.

  • Dodatkowo, dla wszystkich klauzuli try/except należy ograniczać ilość kodu pod klauzulą try do niezbędnego minimum. Również to pomoże unikać błędów.

    Tak:

          try:
              value = collection[key]
          except KeyError:
              return key_not_found(key)
          else:
              return handle_value(value)

    Nie:

          try:
              # Too broad!
              return handle_value(collection[key])
          except KeyError:
              # Will also catch KeyError raised by handle_value()
              return key_not_found(key)
  • Używać metod stringów, a nie modułu string

    Metody stringów są zawsze dużo szybsze i współdzielą to samo API ze stringami unikod.

  • Należy używać ”.startswith() i ”.endswith() zamiast krojenia stringów (string slicing).

    startswith() i endswith() są czystsze i powodują mniej błędów. Na przykład:

    Tak:

          if foo.startswith('bar'):

    Nie:

          if foo[:3] == 'bar':
  • Porównania typów obiektowych powinny zawsze używać konstrukcji isinstance() zamiast porównywać typy bezpośrednio.

    Tak:

          if isinstance(obj, int):

    Nie:

          if type(obj) is type(1):

    Podczas sprawdzania czy obiekt jest stringiem, należy mieć na uwadze, że to również może być string unikodowy! W Pythonie 2.3 string i unikod mają wspólną klasę bazową, basestring, tak więc można zrobić:

          if isinstance(obj, basestring):
  • Dla typów sekwencyjnych, (stringów, list, krotek/tuples/), należy korzystać z faktu, że puste sekwencje są fałszywe.

    Tak:

          if not seq:
          if seq:

    Nie:

          if len(seq)
          if not len(seq)
  • Nie należy pisać stringów, które zawierają znaczący niedrukowalny znak (spacja, tabulator), Niektóre takie znaki nie dają się od siebie odróżnić i niektóre edytory (lub ostatnio, reindent.py) obetną je.
  • Nie wolno porównywać booleanowskich wartości do True lub False używając ==.

    Tak:

          if greeting:

    Nie:

          if greeting == True:

    Jeszcze gorzej:

          if greeting is True:

    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.

By grzeszy on Styczeń 27, 2009 | PEP, Python | A comment?
Tagi: ,

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

Konwencje nazewnictwa

Istnieją pewne rekomendowane konwencje nazewnictwa w Pythonie. Konwencje te powinny być stosowane do nowo pisanych modułów. Nowo pisane pakiety i moduły powinny być utrzymane w tych konwencjach. Kiedy starsza biblioteka reprezentuje inny styl to przy jej rozszerzaniu powinien być zachowany pierwotny styl w celu wewnętrznej spójności.

Nazwy, których należy unikać:

Nie używać jako nazw zmiennych liter l (L jak Leszek), O (O jak Olga) oraz I (i jak Irena). W przypadku pewnych krojów czcionek litery te są nieodróżnialne od liczby jeden oraz zero.

Nazwy pakietów i modułów.

Moduły powinny mieć krótką nazwę wyłącznie z małych liter. Podkreślenia mogą być używane w nazwach modułów jeśli poprawi to czytelność. Podobnie jest w przypadku pakietów (ang. package) jednak nie zaleca się stosować podkreśleń.

Ponieważ nazwy modułów są mapowane do nazw plików powinny one być odpowiednio krótkie. Zbyt długie nazwy mogą być problemem na starszych wersjach Mac, Windows oraz w DOS.

Kiedy rozszerzeniu napisanym w C/C++ towarzyszy moduł Pythona dodający interfejs wyższego poziomu (bardzo zorientowany obiektowo), nazwa rozszerzenia w C/C++ powinna rozpoczynać pojedynczym podkreśleniem (np. _socket)

Nazwy klas

Prawie że bez wyjątków, nazwy klas powinny mieć nazwę w konwencji CapsWords. Klasy do użytku wewnętrznego powinno poprzedzać pojedyncze podkreślenie (_CapsWord).

Nazwy funkcyj

Nazwy funkcyj powinny być pisane małymi literami ze słowami rozdzielanymi przez podkreślenia, jeśli to konieczne aby zwiększyć czytelność (nazwa, nazwa_funkcji)

Argumenty funkcyj i metod

Zawsze należy używać self jako pierwszego argumentu do metody instancji. Zawsze należy używać cls jako pierwszego argumentu do metody klasy.

Jeśli nazwa argumentu funkcji koliduje z nazwą słowa kluczowego Pythona, zazwyczaj lepiej jest dołączyć pojedyncze podkreślenie na końcu nazwy niż tworzyć nieczytelne skróty lub celowe literówki. W związku z tym print_ jest lepsze niż prnt. Dobrze jeśli uda się uniknąć konfliktu przez użycie synonimu.

Nazwy zmiennych globalnych

Nazwy zmiennych globalnych podlegają tym samym konwencjom co nazwy funkcyj. (Zaleca się aby używać zmiennych globalnych tylko wewnątrz jednego modułu)

Moduły, które są zaprojektowane aby używać ich przez from module import * powinny zawierać mechanizm __all__ aby zapobiec eksportowaniu zmiennych globalnych lub stosować starszą konwencję dołączania przedrostka – pojedynczego podkreślenia (co można chcieć zrobić by wskazać te zmienne globalne jako „niepubliczne”).

Nazwy metod i zmiennych instancyj

Stosować zasady dotyczące nazw funkcyj.

Poprzedzające pojedyncze podkreślenie dla niepublicznych metod i zmiennych instancji.

Unikać konfliktu nazw z podklasą przez użycie podwójnego poprzedzającego podkreślenia aby wywołać mechanizm dekorowania nazw Pythona (Python’s mangling rules).

Stałe

Stałe są deklarowane na poziomie modułu i pisane wielkimi literami z pokreśleniami jako separatorami słów. Np. MAX_OVERFLOW i TOTAL.

Konstrukcja ze względu na dziedziczenie

Zawsze należy zdecydować czy metody i zmienne instancji (wspólne określenie to atrybuty) mają być publiczne czy niepubliczne. W razie wątpliwości należy uczynić atrybut niepublicznym, później łatwiej zrobić z niego atrybut publiczny niż na odwrót.

Publiczne atrybuty to te, co do których należy się spodziewać, że będą użyte przez niezwiązane klienty, ze „zobowiązaniem”, że zmiany w module/pakiecie nie będą powodowały niekompatybilności wstecz. Niepubliczne atrybuty to te, które nie są tworzone w zamierzeniu do użycia przez programy trzecie. Nie ma potrzeby zapewniać, że niepubliczne atrybuty nie zmienią się lub nawet nie będą usunięte.

Używa się terminu „niepubliczny” gdyż tak na prawdę żaden atrybut w Pythonie nie jest prywatny.

Kolejna kategoria atrybutów to te, które są częścią „podklasowego API” („subclass API”) – nazywane w innych językach programowania – protected. Niektóre klasy są przeznaczone do dziedziczenia aby rozszerzać lub modyfikować różne aspekty zachowania klasy. Podczas projektowania takiej klasy należy podjąć wyraźne decyzje dotyczące tego jakie atrybuty mają być publiczne, a które są częścią „podklasowego API”, i które będą na prawdę używane tylko przez klasę bazową.

Biorąc pod uwagę powyższe, oto Pythonowe wskazówki.

  • Publiczne atrybuty nie powinny mieć przedniego podkreślenia.
  • Jeśli atrybut koliduje ze słowem kluczowym Pythona, należy dołączyć pojedyncze, kończące podkreślenie.

Zobacz powyższe rekomendacje dla nazewnictwa metod klas.

  • Dla prostych atrybutów z danymi, najlepiej jest ujawnić po prostu nazwę atrybutu bez skomplikowanych metod typu accessor czu mutator. Należy też mieć na uwadze, że Python daje łatwą możliwość rozszerzania funkcjonalności atrybutu jeśli zajdzie taka potrzeba. W takim wypadku używa się właściwości (properties) aby ukryć funkcjonalną implementację atrybutu za prostą składnią dostępu do atrybutu.
    1. Właściwości (properties) działają tylko w nowego typu klasach
    2. ?
    3. Lepiej unikać używania właściwości do drogich obliczeniowo operacji, zapis atrybutu jest traktowany przez wywołującego (caller) jako niewymagający dużych zasobów obliczeniowych.
  • Jeśli klasa w zamierzeniu ma służyć jako przodek (subclass) lecz nie wszystkie atrybuty mają być używane przez podklasę można rozważyć nazwanie ich z podwójnym podkreśleniem na początku nazwy i bez końcowego podkreślenia. To spowoduje wywołanie mechanizmu dekorowania nazwy (mangling), gdzie nazwa klasy jest wdekorowana w nazwę atrybutu. To pomaga unikać kolizji atrybutów gdyby podklasa niezamierzenie zawierała atrybuty o takiej samej nazwie.
    1. Zauważyć należy, że tylko prosta nazwa klasy jest używana w dekorowaniu nazwy, tak więc jeśli podklasa ma zarówno taką samą nazwę klasy jak i nazwę atrybutu nadal istnieje możliwość kolizji nazw
    2. Dekorowanie nazwy czyni pewne zastosowania, jak debugowanie czy __getattr__() mniej wygodnymi. Jakkolwiek algorytm dekorowania nazw jest dobrze udokumentowany i łatwy do wykonania ręcznie.


PEP 8
to jest podręcznik z wytycznymi na temat stylu kodu w Pythonie, a powyższy tekst to moja ściąga z PEP 8, napisana na poziomie mojej wiedzy z języka Python. Ma służyć dla mnie jako pomoc w opanowaniu języka.

Do późniejszego uzupełnienia.

By grzeszy on | PEP, Python | 1 comment
Tagi: ,

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/bibliotekiPowinno 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 &lt; 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 odmienia się identyfikatorów  przez przypadki, np. dla zmiennej „count”, nie napiszemy „zależy od counta”, tylko „zależy od zmiennej count”.
  • 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.

By grzeszy on Grudzień 18, 2008 | PEP, Programowanie, Python | 2 komentarze
Tagi: ,