Przerwa kawowa #103. W obronie „czystego kodu”: 100 ponadczasowych wskazówek

Źródło: Hackernoon „Clean Code” Roberta C. Martina to najczęściej polecana książka o programowaniu wszechczasów. Wyszukaj książki, używając hasła „najlepsze książki dla programistów”, a prawie na pewno znajdziesz tę książkę w wynikach wyszukiwania. I choć niektórzy uważają, że nie warto zwracać uwagi na Czysty Kodeks, to twierdzę, że takie opinie są głęboko błędne. Tak, niektóre rady zawarte w książce są wątpliwe. Tak, niektóre treści wydają się nieaktualne. Tak, niektóre przykłady są mylące. To wszystko prawda. Ale nie spieszmy się z lekceważeniem wielu przydatnych wskazówek, jakie oferuje ta książka! Całkowite ignorowanie Czystego Kodu tylko z powodu kilku złych pomysłów nie jest najlepszym rozwiązaniem. Zatem bez zbędnych ceregieli przyjrzyjmy się najlepszym wskazówkom, jakie ma do zaoferowania Clean Code! Przejrzymy każdy rozdział, podsumowując pomysły zaproponowane przez Wujka Boba i jego współautorów.

Rozdział 1: Czysty kod

1. Ogólna ilość bałaganu zwiększa się z czasem.

2. Przywrócenie przestarzałego systemu od zera jest bardzo trudne. Refaktoryzacja i przyrostowe ulepszenia będą w tym przypadku najlepszą opcją.

3. W nieuporządkowanym kodzie zadania, które powinny zająć tylko kilka godzin, mogą zająć kilka dni lub tygodni.

4. Poświęć trochę czasu na szybkie działanie.

5. Czysty kod robi jedną rzecz dobrze. Zły kod próbuje zrobić zbyt wiele.

6. Czysty kod jest dobrze przetestowany.

7. Czytając dobrze napisany kod, każda funkcja robi mniej więcej to, czego można się spodziewać.

8. Jeśli nie zgadzasz się z zasadą nauczaną przez osobę z wieloletnim doświadczeniem, powinieneś przynajmniej rozważyć jej punkt widzenia, zanim go zignorujesz.

9. Kod jest czytany znacznie częściej niż pisany.

10. Kod łatwiejszy do odczytania jest łatwiejszy do zmiany.

11. Pozostaw bazę kodu w lepszym stanie niż wtedy, gdy ją znalazłeś (Zasada skauta).

Rozdział 2: Znaczenie imion

1. Wybierz ostrożnie nazwy zmiennych.

2. Wybór dobrych imion jest trudny.

3. Nazwa zmiennej lub funkcji powinna wskazywać, czym ona jest i jak jest używana.

4. Unikaj używania jednoznakowych nazw zmiennych, z wyjątkiem powszechnie używanych nazw, takich jak i dla zmiennej licznika w pętli.

5. Unikaj używania skrótów w nazwach zmiennych.

6. Nazwy zmiennych powinny być wymawialne, aby można było o nich mówić i wypowiadać je na głos.

7. Używaj nazw zmiennych, które są łatwe do znalezienia.

8. Klasy i obiekty muszą mieć nazwy w formie rzeczowników.

9. Nazwy metod i funkcji muszą być czasownikami lub parami czasownik-rzeczownik.

Rozdział 3: Funkcje

1. Funkcje powinny być małe.

2. Funkcja musi wykonać jedną akcję.

3. Funkcje muszą mieć nazwy opisowe.

4. Wyodrębnij kod z treści if/else lub zamień instrukcje na wyraźnie nazwane funkcje.

5. Ogranicz liczbę argumentów pobieranych przez funkcję.

6. Jeśli funkcja wymaga wielu argumentów konfiguracyjnych, rozważ połączenie ich w jedną zmienną parametrów konfiguracyjnych.

7. Funkcje muszą być czyste, co oznacza, że ​​nie powodują skutków ubocznych i nie modyfikują argumentów wejściowych.

8. Funkcja musi być poleceniem lub zapytaniem, ale nie obydwoma na raz (rozdzielanie zapytań poleceń).

9. Lepiej usuwać błędy i wyjątki z kodu niż pozostawiać błędy w kodzie.

10. Wyodrębnij zduplikowany kod do wyraźnie nazwanych funkcji (nie powtarzaj się).

11. Testy jednostkowe ułatwiają refaktoryzację.

Rozdział 4: Komentarze

1. Komentarze mogą być nieprawidłowe. Mogą być na początku błędne lub mogą być początkowo dokładne, a z biegiem czasu stają się nieaktualne w miarę zmiany kodu.

2. Użyj komentarzy, aby opisać, dlaczego jest napisany w taki sposób, w jaki jest, zamiast wyjaśniać, co się dzieje.

3. Często można uniknąć komentarzy, używając jasno nazwanych zmiennych i wyodrębniając sekcje kodu do jasno nazwanych funkcji.

4. Dodaj do komentarzy TODO spójne przedrostki, aby ułatwić ich znalezienie. Okresowo przeglądaj i usuwaj swoje komentarze do zadań TODO.

5. Nie używaj Javadocs tylko dla samego korzystania z nich. Komentarze opisujące, co robi metoda, jakie argumenty przyjmuje i co zwraca, są w najlepszym przypadku zbędne, a w najgorszym wprowadzają w błąd.

6. Komentarze powinny zawierać wszystkie istotne informacje i kontekst, których czytelnik będzie potrzebował. Nie bądź leniwy podczas pisania komentarza.

7. Komentarze do dziennika i komentarze autorów plików nie są potrzebne ze względu na kontrolę wersji i winę Gita.

8. Nie komentuj martwego kodu. Po prostu usuń to. Jeśli uważasz, że będziesz potrzebować kodu w przyszłości, właśnie do tego służy kontrola wersji.

Rozdział 5: Formatowanie

1. Jako zespół wybierz zestaw reguł formatowania kodu, a następnie konsekwentnie stosuj te reguły. Bez względu na to, z jakimi zasadami się zgadzasz, musisz dojść do porozumienia.

2. Skorzystaj z automatycznego formatowania kodu i analizatora kodu. Nie polegaj na ręcznym znajdowaniu i naprawianiu każdego błędu formatowania. Jest to nieefektywne, nieproduktywne i stratą czasu podczas przeglądania kodu.

3. Dodaj pionowe odstępy między wierszami kodu, aby wizualnie oddzielić powiązane bloki kodu. Wszystko, czego potrzebujesz, to utworzyć jedną nową linię pomiędzy grupami.

4. Małe pliki są łatwiejsze do odczytania, zrozumienia i przenoszenia niż duże pliki.

5. Zmienne należy deklarować w pobliżu miejsca, w którym są używane. W przypadku małych funkcji jest to zwykle górna część funkcji.

6. Nawet w przypadku krótkich funkcji lub instrukcji if nadal należy je poprawnie formatować, zamiast zapisywać je w jednym wierszu.

Rozdział 6: Obiekty i struktury danych

1. Szczegóły implementacji obiektu muszą być ukryte za interfejsem obiektu. Udostępniając interfejs do użytku przez konsumentów obiektu, ułatwiasz późniejszą refaktoryzację szczegółów implementacji bez powodowania istotnych zmian. Abstrakcje ułatwiają refaktoryzację.

2. Dowolny fragment kodu nie powinien mieć żadnej wiedzy o wewnętrznych elementach obiektu, na którym działa.

3. Pracując z obiektem, powinieneś wymagać od niego wykonania polecenia lub zapytania, zamiast zadawać pytania o jego elementy wewnętrzne.

Rozdział 7: Poprawianie błędów

1. Obsługa błędów nie powinna zakłócać reszty kodu w module.

2. Lepiej usuwać błędy i wyjątki z kodu niż pozostawiać błędy w kodzie.

3. Pisz testy z błędami, aby mieć pewność, że Twój kod je zidentyfikuje i nie przeoczy.

4. Komunikaty o błędach powinny mieć charakter informacyjny i zawierać cały niezbędny kontekst, który może być potrzebny do skutecznego rozwiązania problemu.

5. Opakowanie interfejsów API innych firm cienką warstwą abstrakcji ułatwia zastępowanie jednej biblioteki inną w przyszłości.

6. Opakowanie interfejsów API innych firm cienką warstwą abstrakcji ułatwia kpiny z biblioteki podczas testowania.

7. Użyj wzorca Special Case lub Null Object, aby obsłużyć wyjątkowe zachowanie, na przykład gdy określone dane nie istnieją.

Rozdział 8: Granice

1. Biblioteki innych firm pomagają przyspieszyć dostarczanie produktów, umożliwiając outsourcing różnych zadań.

2. Napisz testy, aby upewnić się, że poprawnie korzystasz z biblioteki strony trzeciej.

3. Użyj wzorca adaptera, aby wypełnić lukę między interfejsem API biblioteki innej firmy a interfejsem API, który chcesz mieć.

4. Opakowanie interfejsów API innych firm cienką warstwą abstrakcji ułatwia zastępowanie jednej biblioteki inną w przyszłości. (Powtórz od rozdziału 7)

5. Opakowanie interfejsów API innych firm cienką warstwą abstrakcji ułatwia kpiny z biblioteki podczas testowania. (Powtórz od rozdziału 7)

6. Staraj się nie przekazywać aplikacji zbyt wielu informacji o szczegółach bibliotek stron trzecich.

7. Lepiej polegać na tym, na co masz wpływ, niż na tym, na co nie masz wpływu.

Rozdział 9: Testy jednostkowe

1. Kod testowy powinien być tak czysty jak kod produkcyjny (z pewnymi wyjątkami, zwykle związanymi z pamięcią lub wydajnością).

2. Wraz ze zmianą kodu produkcyjnego zmienia się także kod testowy.

3. Testy pomagają zachować elastyczność i łatwość konserwacji kodu produkcyjnego.

4. Testy pozwalają na wprowadzanie zmian, pozwalając na pewną refaktoryzację bez obawy, że sam tego nie zauważysz.

5. Ustrukturyzuj swoje testy, korzystając ze wzorca Ułóż-Działaj-Potwierdź (znanego również jako Budowa-Obsługa-Sprawdzenie, Konfiguracja-Ćwiczenie-Weryfikacja lub Biorąc-Kiedy-Wtedy).

6. Użyj funkcji specyficznych dla domeny, aby ułatwić pisanie i czytanie testów.

7. Oceń jedną koncepcję w teście.

8. Testy muszą być szybkie.

9. Testy muszą być niezależne.

10. Testy muszą być powtarzalne.

11. Testy nie powinny wymagać potwierdzenia.

12. Testy należy pisać terminowo, na krótko przed lub po napisaniu kodu produkcyjnego, a nie kilka miesięcy później.

13. Jeśli Twoje testy wypadną źle, spodziewaj się błędów w kodzie.

Rozdział 10: Zajęcia

1. Klasy powinny być małe.

2. Klasy powinny być odpowiedzialne tylko za jedną rzecz i mieć tylko jeden powód do zmiany (zasada pojedynczej odpowiedzialności).

3. Jeśli nie możesz wymyślić jasnej nazwy klasy, prawdopodobnie jest ona za duża.

4. Twoja praca nie kończy się w momencie uruchomienia fragmentu kodu. Następnym krokiem będzie refaktoryzacja i oczyszczenie kodu.

5. Używanie w aplikacji wielu małych klas zamiast kilku dużych klas zmniejsza ilość informacji, które programista musi zrozumieć podczas pracy nad danym zadaniem.

6. Posiadanie dobrego zestawu testów pozwala na pewną refaktoryzację podczas dzielenia dużych klas na mniejsze.

7. Zajęcia powinny być otwarte na rozbudowę, ale zamknięte na modyfikację (zasada otwarte-zamknięte).

8. Interfejsy i klasy abstrakcyjne tworzą szwy, które ułatwiają testowanie.

Rozdział 11: Systemy

1. Użyj wstrzykiwania zależności, aby zapewnić programistom elastyczność przekazywania dowolnego obiektu z odpowiednim interfejsem do innej klasy.

2. Użyj wstrzykiwania zależności, aby utworzyć interfejsy między obiektami w aplikacji, aby ułatwić testowanie.

3. Systemy oprogramowania nie przypominają budynku, który należy wcześniej zaprojektować. Przypominają raczej miasta, które z biegiem czasu rosną i rozrastają się, dostosowując się do aktualnych potrzeb.

4. Odłóż podjęcie decyzji do ostatniego krytycznego momentu.

5. Używaj języka specyficznego dla domeny, aby eksperci domeny i programiści używali tej samej terminologii.

6. Nie komplikuj zbytnio swojego systemu. Użyj najprostszej rzeczy, która działa.

Rozdział 12: Wdrożenie

1. Systemów, których nie można przetestować, nie można zweryfikować, a systemów, których nie można zweryfikować, nie należy nigdy wdrażać.

2. Pisanie testów prowadzi do lepszego projektowania, ponieważ łatwy do przetestowania kod często wykorzystuje wstrzykiwanie zależności, interfejsy i abstrakcję.

3. Dobry zestaw testów wyeliminuje strach przed uszkodzeniem aplikacji podczas refaktoryzacji.

4. Powielanie kodu stwarza większe ryzyko, ponieważ w kodzie jest więcej miejsc, które można zmienić, a jeszcze więcej miejsc, w których można ukryć błędy.

5. Kod, który teraz piszesz, jest łatwiejszy do zrozumienia, ponieważ jesteś głęboko zaangażowany w jego zrozumienie. Innym nie jest łatwo szybko osiągnąć ten sam poziom zrozumienia.

6. Większość kosztów projektu oprogramowania wiąże się z długoterminowym utrzymaniem.

7. Testy służą jako żywa dokumentacja tego, jak aplikacja powinna (i zachowuje się) zachowywać.

8. Nie ruszaj się dalej, gdy kod zacznie działać. Poświęć trochę czasu, aby uczynić go jaśniejszym i bardziej zrozumiałym.

9. Następną osobą, która w najbliższej przyszłości przeczyta Twój kod, najprawdopodobniej będziesz Ty. Bądź miły dla siebie w przyszłości, pisząc kod, który jest łatwy do zrozumienia.

10. Sprzeciwiaj się dogmatom. Ogarnij pragmatyzm.

11. Aby stać się naprawdę dobrym inżynierem oprogramowania, potrzeba dziesięcioleci. Możesz przyspieszyć proces uczenia się, ucząc się od otaczających Cię ekspertów i ucząc się powszechnie używanych wzorców projektowych.

Rozdział 13: Równoległość

1. Pisanie kodu równoległego jest trudne.

2. Sporadyczne błędy i problemy trudne do odtworzenia są często problemami współbieżności.

3. Testowanie nie gwarantuje, że Twoja aplikacja będzie wolna od błędów, ale zminimalizuje ryzyko.

4. Dowiedz się o typowych problemach ze współbieżnością i możliwych rozwiązaniach.

Rozdział 14: Udoskonalanie sekwencyjne

1. Czysty kod zwykle nie zaczyna się od pustej karty. Najpierw piszesz przybliżone rozwiązanie, a następnie refaktoryzujesz je, aby było czystsze.

2. Błędem jest zaprzestanie pracy nad kodem, gdy już zaczął on działać. Poświęć trochę czasu, aby uczynić go jeszcze lepszym, gdy już działa.

3. Niepokój narasta stopniowo.

4. Jeśli znajdziesz się w trudnej sytuacji, w której dodawanie funkcji jest zbyt trudne lub zajmuje zbyt dużo czasu, przestań pisać funkcje i rozpocznij refaktoryzację.

5. Stopniowe zmiany są często lepsze niż budowanie od zera.

6. Użyj programowania opartego na testach (TDD), aby wprowadzić dużą liczbę bardzo małych zmian.

7. Dobry projekt oprogramowania wymaga oddzielenia problemów w kodzie i podzielenia kodu na mniejsze moduły, klasy i pliki.

8. Łatwiej posprzątać bałagan od razu po jego zrobieniu, niż później.

Rozdział 15: Elementy wewnętrzne JUnit

1. Ujemne nazwy zmiennych lub wyrażenia warunkowe są nieco trudniejsze do zrozumienia niż dodatnie.

2. Refaktoryzacja to proces iteracyjny, pełen prób i błędów.

3. Pozostaw bazę kodu w lepszym stanie niż wtedy, gdy ją znalazłeś (Zasada skauta). (Powtórzone z rozdziału 1)

Rozdział 16: Refaktoryzacja SerialDate

1. Recenzje kodu i krytyka naszego kodu czynią nas lepszymi i powinniśmy to przyjąć z radością.

2. Najpierw spraw, aby kod działał, a potem go napraw.

3. Nie każda linia kodu wymaga testowania.

Rozdział 17: Zapachy i heurystyka

1. Czysty kod to nie zbiór zasad, a raczej system wartości, które decydują o jakości Twojej pracy.

[W tym rozdziale Wujek Bob wymienia 66 kolejnych odmian swojego kodu i heurystyk, z których wiele omówiono w dalszej części książki. Powielanie ich tutaj zasadniczo oznaczałoby skopiowanie i wklejenie nazwy każdego elementu, więc powstrzymałem się od tego. Sugeruję zamiast tego przeczytanie książki!]

Wniosek

Zakończmy tam, gdzie zaczęliśmy: Czysty kod Roberta C. Martina to najczęściej polecana książka o programowaniu wszechczasów. Jest ku temu dobry powód.