pjn-2024-cw/00_czysty_kod.ipynb

Czysty kod

Gorąco zachęcam do przeczytania książki: Czysty kod. Podręcznik dobrego programisty

Co to znaczy "czysty kod"?

Czysty kod to taki zapis kodu, który będzie czytelny/przyjazny dla innych osób (lub samego siebie przy powrocie do danego kodu po kilku miesiącach przerwy)

Czysty kod powinien być:

• poprawnie sformatowany (dla chętnych dokument PEP 8 opisujący formatowanie kodu w Pythonie https://peps.python.org/pep-0008/)
• samoopisywalny - nazwy zmiennych/funkcji powinny opisywać, co dzieje się w danym fragmencie kodu
• możliwie krótki i prosty (brak wielokrotnych zagnieżdżeń, wielu różnych wariantów w blokach if-elif-else itp.)

1. Nazwy:

• Znaczące i opisowe: Nazwy zmiennych, funkcji i klas powinny jasno wskazywać ich przeznaczenie (czyli definiować, z czym mamy doczynienia). Krótka nazwa to nie zawsze dobra nazwa! Przykłady:
  • words zamiast w
  • number_of_ill_patients jako liczba chorych pacjentów. Jeśli chcielibyśmy przetrzymywać listę/zbiór chorych pacjentów (obiektów posiadających informacje o pacjentach), wtedy możemy skorzystać ze zmiennej ill_patients.
  • calculate_sum() zamiast calc()
  • nazwy takie jak x czy y możemy wykorzystywać w takich zastosowaniach jak indeks podczas iterowania pętli
• Konwencja: Używaj snake_case dla nazw zmiennych i funkcji (małe litery, podkreślenia). Klasy piszemy w CamelCase (duże litery na początku każdego słowa).
• Unikaj skrótów: unique_elements zamiast uni_elem, wyjątek stanowią skróty, które są jednoznaczne, powszechnie przyjęte i rozumiane przez zdecydowaną większość osób mających styczność z kodem (np. number -> num, dataframe -> df, vocabulary -> vocab, character -> char).

2. Formatowanie:

• Wcięcia: Używaj 4 spacji na każde wcięcie.
• Puste linie: Oddzielaj bloki kodu pustymi liniami dla lepszej czytelności (funkcje, klasy, oraz fragmenty kodu staniowące pewną logiczną spójność).
• Długość linii: Staraj się, aby linie kodu nie były dłuższe niż 80 znaków.

3. Funkcje:

• Jedno zadanie: Każda funkcja powinna wykonywać tylko jedno, konkretne zadanie.
• Krótkie i zwięzłe: Funkcje powinny być krótkie i łatwe do zrozumienia (tak samo ich nazwy).

4. Komentarze:

• Podstawowa zasada: W komentarzu umieszczaj informacje, których nie da się wyrazić w kodzie, a które są ważne.
• Unikaj nadmiaru komentarzy: Zbyt wiele komentarzy może utrudnić czytanie kodu.

5. Moduły i pakiety:

• Organizacja: Dziel duży kod na mniejsze moduły i pakiety, aby ułatwić jego zarządzanie.
• Import: Importuj tylko niezbędne moduły.

Narzędzia:

• Linters: Używaj linterów, takich jak pylint lub flake8, aby automatycznie sprawdzać styl i jakość kodu.
• Formatery: Używaj formaterów kodu, takich jak black lub autopep8, aby automatycznie formatować kod zgodnie z ustalonymi konwencjami.

Pamiętaj: Celem czystego kodu jest jego zrozumienie i utrzymanie. Inwestycja w czysty kod zaoszczędzi Ci (oraz Twoim współpracownikom) czasu i wysiłku w przyszłości.

Przykład nieczytelnego kodu

with open("file1.txt", "r") as f:
    b = f.readlines()
    b = [x.strip() for x in b]
    b = set(b)
with open("file2.txt", "r") as f:
    a = f.readlines()
    a = [x.strip() for x in a]
    a = " ".join(a)

a = a.split()

aa = []
for a1 in a:
    aaa = "".join([c for c in a1 if c.isalpha()])
    aa.append(aaa)

o = []
for a2 in aa:
    if a2 not in b:
        o.append(a2)
        
print(o)

Przykład wyżej po poprawie

def remove_nonletters_chars(words):
    filtered_words = []

    for word in words:
        filtered_word = "".join([char for char in word if char.isalpha()])
        filtered_words.append(filtered_word)
    
    return filtered_words


def get_out_of_vocab_words(text, vocab):
    words = text.split()
    words = remove_nonletters_chars(words)
    
    out_of_vocab_words = []
    for word in words:
        if word not in vocab:
            out_of_vocab_words.append(word)
    
    return out_of_vocab_words

with open("vocabulary.txt", "r") as file:
    vocab = file.readlines()
    vocab = [x.strip() for x in vocab]
    vocab = set(vocab)

with open("article.txt", "r") as file:
    article = file.readlines()
    article = [x.strip() for x in article]
    article = " ".join(article)

out_of_vocab_words = get_out_of_vocab_words(article, vocab)
print(out_of_vocab_words)

W powyższym kodzie:

• zmienne jednoznacznie wskazują "czym" są
• nazwy funkcji opisują co w nich jest wykonywane
• fragmenty kodu są właściwie oddzielone nowymi liniami
• kod nie zawiera komentarzy, ponieważ strukturę działania programu dało się wyrazić poprzez nadanie właściwych nazw zmiennym oraz funkcjom