Skąd można wiedzieć, czy utworzony przez siebie kod jest łatwy do odczytania, zrozumienia i utrzymania? Oczywiście z punktu widzenia autora kod jest czytelny i łatwy do utrzymania, ponieważ autor napisał go i zredagował na początek. Jednak musi istnieć obiektywny i wymierny standard, według którego nasz zawód może mierzyć kod.
Cele te są osiągane, gdy można wykonać następujące czynności przy użyciu kodu bez porady eksperta oryginalnego autora:
Możliwe jest odczytanie kodu i zrozumienie na poziomie podstawowym przepływu logiki.
Na głębszym poziomie można zrozumieć, co robi kod, aby uwzględnić dane wejściowe, wyjściowe i algorytmy.
Inni programiści mogą wprowadzać znaczące zmiany w oryginalnym kodzie, takie jak poprawki błędów lub refaktoryzacja.
Można napisać nowy kod, taki jak klasa lub moduł, który wykorzystuje oryginalny kod.
Jak kwantyfikujemy lub mierzymy jakość kodu, aby wiedzieć, że jest on czytelny, zrozumiały i łatwy w utrzymaniu?
Odpowiedzi:
Twój rówieśnik powie ci po przejrzeniu kodu.
Nie możesz tego ustalić sam, ponieważ jako autor wiesz więcej niż sam kod mówi. Komputer nie może ci powiedzieć z tych samych powodów, z których nie może stwierdzić, czy obraz jest sztuką, czy nie. Dlatego potrzebujesz innego człowieka - zdolnego do utrzymania oprogramowania - aby spojrzeć na to, co napisałeś i wyrazić swoją opinię. Formalna nazwa tego procesu to wzajemna ocena .
źródło
Czasami najlepszym sposobem na to jest powrót do kodu napisanego sześć miesięcy temu i próba zrozumienia, co zostało napisane.
Jeśli szybko to zrozumiesz - jest czytelny.
źródło
To jest:
Prawdziwym testem na 1. jest (jak twierdzą Alex w Paryżu i quant_dev ), że możesz go odzyskać po kilku miesiącach robienia czegoś innego.
Test na 2. i 3. polega na tym, że ktoś inny może go podnieść i dowiedzieć się, jak rozszerzyć lub naprawić kod, postępując zgodnie z projektem. Jeśli nie potrafią zrozumieć projektu, jego związku z przestrzenią problemową lub sposobu, w jaki twój kod ma być używany, zamiast tego zhakują rozwiązanie w poprzek ziarna.
Istnieją zasady praktyczne, zasady (tj. Zasady praktyczne, które ktoś ładnie napisał i podał imię) oraz wszelkiego rodzaju sugestie, które mogą poprowadzić cię we właściwym kierunku lub z dala od typowych pułapek. Żaden z nich nie gwarantuje jednak jakości, o którą prosisz.
źródło
Jeśli Twój kod jest zgodny z zasadami SOLID i DRY i ma w nim dobry zestaw testów jednostkowych, prawdopodobnie można go utrzymać.
Czy to jest czytelne? Przeczytaj to. Czy nazwy metod i zmiennych mają sens? Czy potrafisz bez problemu podążać za logiką programu? Jeśli odpowiedź brzmi „tak”, kod jest czytelny.
źródło
Czytanie, jak pisać nieusuwalny kod - Roedy Green zapewnia pracę na całe życie , śmiejąc się i ucząc.
Esej zawiera wiele przykładów pisania złego kodu, przy użyciu wielu zabawnych przykładów. W dalszym ciągu wyjaśnia, w jaki sposób wykorzystać twórczą pisownię , ponowne użycie nazw , wysoko cenioną technikę ponownego wykorzystywania nazw globalnych jako prywatnych .
W zabawny sposób esej uczy, jak unikać wszystkich przykładów nieczytelnego i niemożliwego do utrzymania kodu.
W rzeczywistości trudno mi było uwierzyć, że ktoś napisałby kod podobny do przykładów w tekście. To było, kiedy byłem świeżo po szkole. Ale po kilku latach pracy codziennie widzę kod z tekstu…
źródło
Pomimo tego, jak się wydaje, istnieją pewne dość obiektywne środki, które można rozważyć. Książki takie jak Standardy kodowania C ++ , Refaktoryzacja i Czysty kod mają długie listy kryteriów, według których można oceniać kod, patrząc na takie znaczące nazwy, rozmiary funkcji, zasady takie jak łączenie i spójność, projektowanie obiektów, testowanie jednostek, kolejne udoskonalanie itp.
Lista jest zbyt duża, aby można ją było dostosować do listy kontrolnej, ale czytasz książkę i wybierasz kilka kluczowych rzeczy, nad którymi chcesz popracować, a następnie po kilku miesiącach przeczytaj ją jeszcze raz, aby poprawić.
źródło
Dowód jest w budyniu. Zobacz, co się stanie po przekazaniu go rozsądnie kompetentnej osobie. Jeśli nie muszą zadawać wielu pytań dotyczących trudności kodu, wykonałeś dobrą robotę.
To była wczesna lekcja w mojej karierze. Mentor powiedział: „Dokumentuj wszystko, abyś mógł później uciec z programu. Jeśli nie spodziewasz się pytań, kiedy odpowiedzi będą świeże w twoim umyśle, będziesz musiał je zrozumieć, kiedy nie są”.
źródło
Przeczytałem wszystkie odpowiedzi i zauważyłem, że nikt nie wspomniał o złożoności kodu.
Istnieje ścisła korelacja między złożonością kodu a czytelnością / utrzymywalnością. Istnieje wiele algorytmów oceny złożoności kodu, ale porozmawiam o tym, jak działa ocenianie złożoności McCabe.
Zasadniczo, punktacja McCabe czyta twój kod i oblicza liczbę unikalnych „ścieżek”, które przez niego przechodzą. Jeśli użyjesz McCabe jako licznika, a wierszy kodu jako mianownika, uzyskasz całkiem niezłe przybliżenie „czytelności”.
Jeśli masz 10 linii kodu i istnieje 300 ścieżek przez ten kod, to jest to dość nieusuwalny kod (trudny do zmiany w bezpieczny i łatwy sposób) i prawdopodobnie nie jest bardzo czytelny. I odwrotnie, jeśli masz 300 linii kodu, ale jest tylko jedna ścieżka (nie ma żadnych warunków), jest on czytelny i łatwy w utrzymaniu.
Jednak McCabe upada w tym ostatnim przykładzie. Jeśli mam 300 linii kodu bez żadnych warunków, to jest naprawdę duża szansa, że zrobiłem „ponowne użycie kopiuj / wklej”, i oczywiście to też nie jest dobra rzecz. Istnieją więc ogólnosystemowe wskaźniki, które stosujesz oprócz McCabe - takie jak wykrywanie duplikatów lub prawie duplikatów.
źródło
Jedną kwestią, którą podzielę, jest to, że kod jest wbudowany w „moduły”, a kiedy mówię, że mam na myśli to, że możesz zmienić jedną rzecz w module i łatwo pracować z całością. Eliminuje efekty między niepowiązanymi rzeczami. Również:
Bardzo polecam lekturę, The Pragmatic Programmer.
źródło
Niektóre testy / wskaźniki:
Wyłącz IDE. Czy nadal potrafisz odczytać własny kod? Kiedy pojawia się błąd, czy dość łatwo jest go ręcznie prześledzić i dowiedzieć się, w której klasie potrzebujesz punktu przerwania, aby dowiedzieć się, na czym polega problem? Lub kiedy korzystasz z IDE, po prostu nie zawracasz sobie głowy krokiem od samego początku?
Debugowanie często staje się grą wack-a-mole, w której naprawienie jednego błędu tworzy 2+ więcej.
Od pociągnięcia za spust do czegoś użytecznego, co faktycznie się dzieje, ile wywołań metod? Ile metod przekazuje dokładnie takie same lub większość tych samych dokładnych parametrów do innego wywołania metody?
Ile plików musisz otworzyć, aby po prostu dodać prostą nową metodę do klasy?
Pomyśl o przyjętych wzorcach i praktykach. Czy zrobiłeś to, ponieważ miały doskonały sens, czy też dlatego, że ktoś przekonał cię, że „to jedyny sposób, aby to zrobić?” lub dlatego, że chciałeś to w swoim życiorysie lub dlatego, że powiedział to jakiś deweloper rockstar.
źródło
Możesz zlokalizować łatwy w utrzymaniu i czytelny kod, szukając następujących właściwości:
źródło
Jednym słowem: Doświadczenie .
Aby rozpocząć, musisz wykonać gruntowne prace, więc nie mogę zalecić, aby programiści poświęcili czas na czytanie książek, takich jak Refaktoryzacja , która zapewni niektóre z bardziej niezbędnych narzędzi w arsenale programistów, które poprawią twoją zdolność do utrzymywania kodu oraz Clean Code, który został napisany przez jedne z najbardziej rozpoznawalnych talentów w naszej dziedzinie i który opisuje prawie wszystko, co musisz zrozumieć, aby Twój kod był czysty i czytelny.
Żadna ilość lektury nie zastąpi jednak ciężko zarobionego doświadczenia. Naprawdę musisz pracować z kodem przez chwilę, aby w pełni docenić różnicę, jaką może mieć dbałość o jakość kodu. Doświadczając przyjemności pracy z czystym, dobrze przemyślanym kodem, a także bólu związanego ze spaghetti kodowym, uczysz się lepiej rozumieć, czego autorzy tych książek naprawdę chcieli cię nauczyć, ale robisz to w szerszym kontekście prawdziwego kodu produkcyjnego na żywo, gdzie jakość tego, co robisz, naprawdę ma znaczenie i wpływa na twoją zdolność do łatwej pracy z kodem na codzień.
Pomaga także mieć dobrego mentora lub równorzędnego specjalistę z doświadczeniem, który potwierdza, że wkładasz wysiłek w pisanie kodu na wysokim poziomie. To tylko jeden z powodów, dla których recenzje kodów mogą być tak przydatne. Korzystanie z narzędzi do sprawdzania i formatowania kodu może być również bardzo przydatną pomocą w utrzymaniu porządku. Nic jednak nie może się równać z doświadczeniem zdobytym przez lata pisania oprogramowania, tak, że automatycznie piszesz kod, który jest czysty, czytelny i ustrukturyzowany po prostu dla ułatwienia konserwacji, a wszystko dlatego, że przyzwyczaiłeś się stosować do tego najlepsze praktyki długo.
źródło
Nie będąc purytańskim: preferuj funkcjonalny styl. Obecnie większość języków (.NET, Ruby, Python, JavaScript itp.) Obsługuje je i promuje (np. LINQ, underscorejs).
Jest niezwykle łatwy do odczytania.
Zmusza każdy węzeł do pojedynczego, skoncentrowanego zamiaru, który zapewnia jasność celu. A ponieważ każde dyskretne zadanie jest izolowane, wyskakiwanie, podłączanie i przestawianie węzłów (operacji) na różne cele jest banalne. Zapewnia to łatwość konserwacji.
źródło
Czytelny i łatwy do utrzymania kod: Kod, który na pierwszy rzut oka programista rozumie wystarczająco dobrze, aby móc:
Sprowadza się to do „przejrzystości”. tzn. ile pytań programiści muszą zadać konkretnemu segmentowi kodu, zanim będą pewni, że „rozumieją, co robi wystarczająco dobrze”, aby zrealizować bieżące zadanie bez powodowania nieoczekiwanych efektów ubocznych.
Książka „Code Complete, autor: Steve McConnell” porusza ten temat bardzo szczegółowo.
Przegląda różne mierniki, których można użyć, aby ustalić, czy kod jest dobrej jakości.
Zobacz przykład tutaj: http://books.google.co.uk/books?id=3JfE7TGUwvgC&lpg=PT376&pg=PT389#v=onepage&q&f=false
źródło
Minimalizuj skutki uboczne (najlepiej nie mają żadnych)
Funkcja, która powoduje 3 zmiany stanów poza swoim zakresem, jest znacznie trudniejsza do uzasadnienia i utrzymania niż ta, która po prostu wprowadza coś i wyprowadza coś innego. Nie możesz po prostu wiedzieć, co robi funkcja, musisz pamiętać, co ona zrobiła i jak to wpływa na wszystkie inne istotne funkcje.
Dla OOP minimalizacja skutków ubocznych oznacza także klasy z mniejszą liczbą członków, a zwłaszcza mniejszą liczbą członków, którzy mogą modyfikować stan klasy, ponieważ funkcje składowe mogą modyfikować stany poza własnymi i wywoływać skutki uboczne (mogą np. Manipulować wewnętrznymi elementami klasy). Oznacza to również klasy z mniejszą liczbą własnych elementów danych, dzięki czemu metody te mają mniejszy wpływ i mniej skutków ubocznych, które mogą powodować.
Jako prosty przykład wyobraź sobie próbę zaprojektowania fantazyjnej struktury danych, która może utrzymywać
sorted
stan, którego używa do określania, czy należy wyszukiwać binarnie czy liniowo. W takim przypadku przydatne może być podzielenie projektu na dwie klasy. Wywołaniesorted
nieposortowanej klasy może wówczas zwrócić strukturę danych innej klasy, która zawsze utrzymuje posortowaną zawartość. Teraz masz mniej skutków ubocznych (a więc mniej podatnych na błędy i łatwiejszy do zrozumienia kodu), a także kod o szerszym zastosowaniu (poprzedni projekt byłby marnotrawny zarówno w przetwarzaniu, jak i ludzkiej wydajności intelektualnej w przypadku małych tablic, które nigdy nie muszą być sortowane).Unikaj zbędnych zewnętrznych zależności
Możesz być w stanie zaimplementować najbardziej zwięzły kod, jaki można sobie wyobrazić, przy maksymalnym ponownym użyciu kodu, używając 13 różnych bibliotek do wykonania stosunkowo prostego zadania. Przenosi to jednak na czytelników koszty intelektualne, zmuszając ich do zrozumienia przynajmniej części 13 różnych bibliotek. Ta wrodzona złożoność powinna być natychmiast doceniona przez każdego, kto próbował zbudować i zrozumieć bibliotekę strony trzeciej, która wymagała wciągnięcia i zbudowania kilkunastu innych bibliotek do funkcjonowania.
Jest to prawdopodobnie bardzo kontrowersyjny pogląd, ale wolałbym trochę skromnego powielania kodu od przeciwnej skrajności, pod warunkiem, że wynik końcowy zostanie dobrze przetestowany (nic gorszego niż niesprawdzony wadliwy kod wielokrotnie powielany). Jeśli do wyboru jest 3-liniowy duplikat kodu do obliczenia wektorowego produktu krzyżowego lub pobranie epickiej biblioteki matematycznej tylko po to, by zgolić 3 linie kodu, sugerowałbym tę pierwszą, chyba że cały zespół jest zaangażowany w tę bibliotekę matematyczną , w którym momencie nadal możesz rozważyć napisanie 3 wierszy kodu zamiast 1, jeśli jest to wystarczająco trywialne w zamian za korzyści oddzielenia.
Ponowne użycie kodu jest działaniem równoważącym. Ponowne użycie zbyt wiele i przenosisz złożoność intelektualną w jeden do wielu sposobów, ponieważ w tych 3 wierszach prostego kodu, który zapisałeś powyżej, kosztem jest to, że czytelnicy i opiekunowie muszą zrozumieć znacznie więcej informacji niż 3 linie kodu . Powoduje to również, że kod jest mniej stabilny, ponieważ jeśli zmieni się biblioteka matematyczna, to również może zmienić kod. Ponowne użycie zbyt mało, a także zwielokrotnienie narzutu intelektualnego, a Twój kod przestaje korzystać z centralnych ulepszeń, więc jest to działanie równoważące, ale warto wspomnieć o tym, że jest to działanie równoważące, ponieważ próba wyeliminowania każdej najmniejszej formy skromnego powielania może prowadzić do wyniku, który jest tak trudny do utrzymania, jeśli nie większy, niż przeciwna skrajność.
Przetestuj bzdury
To jest pewne, ale jeśli twój kod nie obsługuje wszystkich przypadków wejściowych i pomija niektóre przypadki skrajne, to jak możesz oczekiwać, że inni zachowają napisany przez ciebie kod, którego nawet nie dostałeś przed przesłaniem go do oczu i rąk? Wystarczająco trudno jest wprowadzić zmiany w kodzie, który działa idealnie, nie mówiąc już o kodzie, który nigdy nie był całkiem właściwy.
Ponadto kod, który przechodzi gruntowne testy, zwykle znajdzie mniej powodów do zmiany. Odnosi się to do stabilności, która jest jeszcze bardziej świętym Graalem do osiągnięcia niż do utrzymania, ponieważ stabilny kod, którego nigdy nie trzeba zmieniać, nie wiąże się z żadnymi kosztami utrzymania.
Dokumentacja interfejsu
Jeśli nie możesz poświęcić równego czasu na dokumentowanie obu, nadaj priorytet „tym, co robią” nad „tym, jak to robią”. Przejrzysty interfejs, który jest oczywisty w swoich zamiarach dotyczących tego, co zrobi (a przynajmniej, co powinien zrobić) we wszystkich możliwych przypadkach wejściowych, zapewni przejrzystość kontekstu dla jego własnej implementacji, która pomoże zrozumieć nie tylko, w jaki sposób korzystać z kodu, ale także jak to działa.
Tymczasem kod, który nie ma tych cech, w którym ludzie nawet nie wiedzą, co powinien zrobić, jest SOL bez względu na to, jak dobrze udokumentowane są szczegóły jego implementacji. 20-stronicowy podręcznik implementacji kodu źródłowego jest bezwartościowy dla osób, które nawet nie potrafią dokładnie ustalić, w jaki sposób powinien on być użyty w ogóle i co powinien zrobić we wszystkich możliwych scenariuszach.
Po stronie implementacji priorytetowo udokumentuj to, co robisz inaczej niż wszyscy inni. Na przykład Intel ma ograniczoną hierarchię woluminów dla swoich jąder raytracingu. Ponieważ pracuję w tej dziedzinie, mogę szybko rozpoznać większość tego, co robi ich kod, bez konieczności przeszukiwania dokumentacji. Robią jednak coś wyjątkowego, co polega na przemierzaniu BVH i równoległym wykonywaniu skrzyżowań przy użyciu pakietów promieni . Właśnie tam chcę, aby priorytetowo traktowali swoją dokumentację, ponieważ te części kodu są egzotyczne i niezwykłe z większości historycznych implementacji BVH.
Czytelność
Ta część jest bardzo subiektywna. Nie dbam tak bardzo o czytelność, która jest bliska procesom myślowym człowieka. Najbardziej dobrze udokumentowany kod opisujący rzeczy na najwyższym poziomie nadal jest dla mnie trudny do naśladowania, jeśli autor używa dziwnych i skomplikowanych procesów myślowych do rozwiązania problemu. Tymczasem zwięzły kod używający 2 lub 3 znaków może często być dla mnie łatwiejszy do zrozumienia, jeśli logika jest bardzo prosta. Myślę, że możesz przejrzeć recenzję i zobaczyć, co wolą inni ludzie.
Najbardziej interesuje mnie łatwość utrzymania, a co ważniejsze, stabilność. Kod, który nie znajduje powodów do zmiany, to taki, który ma zerowe koszty utrzymania.
źródło
Powiedziałbym, że jednym ze sposobów byłoby wiedzieć, czy nowi członkowie zespołu mogą pobrać kod, zrozumieć go i zmodyfikować, aby naprawić usterki / spełnić nowe wymagania ze względną łatwością.
źródło
Oto technika, którą lubię stosować:
Pokaż kod jednemu z programistów równorzędnych i poproś go o wyjaśnienie, co robi. Uważaj na te rzeczy.
1) Jeśli nie są w stanie łatwo wyjaśnić celu bloku kodu, należy go refaktoryzować.
2) Jeśli muszą przeskoczyć do innej sekcji kodu, aby zrozumieć bieżącą sekcję, przeprowadź ją ponownie.
4) Za każdym razem, gdy poczujesz potrzebę przemawiania w trakcie procesu, ta część kodu wymaga refaktoryzacji. (Kod nie mówi sam za siebie).
źródło
Najbardziej konserwowalnym kodem jest kod, którego nie ma. Zamiast więc dodawać do liczby LOC nowy kod, który „zmniejsza” liczbę LOC (nawet jeśli jest nieco trudniejszy do utrzymania, gdy oglądany jest w izolacji), może sprawić, że cała baza kodu będzie łatwiejsza w utrzymaniu, po prostu poprzez zmniejszenie jej rozmiaru. Zatem podstawowa reguła dla utrzymywalnego kodu:
Po drugie, nie ma nic gorszego w utrzymywalności niż ukryte zależności. Tak więc dla reguły numer 2:
Po trzecie, nie wszyscy programiści są równie wykwalifikowani w utrzymywaniu lub pisaniu przy użyciu specyficznych, bardziej zaawansowanych technik języka lub idiomów. Ogłuszenie całej bazy kodu da ci dużą bazę kodu, która ze względu na swój rozmiar jest trudna do utrzymania. Zezwalanie na funkcje i idiomy zaawansowanych technik w całym kodzie sprawią, że cały kod będzie obsługiwany tylko przez starszych programistów, co również jest złe. Kluczem do utrzymania jest warstwowanie oparte na poziomie umiejętności Na przykład:
Biblioteki między projektami: seniorzy, pełny kod sztuczek kod / idiom / techniki Biblioteki specyficzne dla projektu i backend systemu: średni deweloperzy, unikaj najbardziej zaawansowanych i trudnych do wyjaśnienia rzeczy. Seniorzy przejdą przez ten kod w poszukiwaniu możliwości ulepszenia SUCHEGO.
Front-end: młodsi deweloperzy, używaj ścisłego przewodnika po stylu i zestawu technik konstruktorów językowych i idiomów, których należy unikać. Medior devs przejdzie przez ten kod w poszukiwaniu SUCHYCH możliwości i ukrytej logiki biznesowej.
Tak więc dla reguły numer 3:
ja
źródło
Nigdy nie jest zbyt łatwo pisać czytelny i łatwy w utrzymaniu kod, ale nie jest trudno napisać łatwy i łatwy do utrzymania kod.
OOAD to czteroliterowe słowo, ale trudno je zrozumieć za jednym razem - podążaj za obiektową analizą i projektowaniem
Zawsze zaczynaj od dobrego zebrania wymagań i dokładnego opisu problemu
Musisz utrzymywać luźne sprzężenie obiektów i upewnić się, że kod się nie powtórzy - postępuj zgodnie z DRY [Nie powtarzaj się]
źródło