Czy możliwe jest ułatwienie odczytu długiego kodu reprezentującego obliczenia?

9

Długie metody są ogólnie uważane za złe, jednak w moim kodzie mam kilka trudnych do zrozumienia długich metod (ponad 50 wierszy). Mam problem z ułatwieniem odczytu tych metod, ponieważ pojedyncza instrukcja ma już ponad 50 wierszy, a ta trudna do odczytania pojedyncza instrukcja polega na zbudowaniu zapytania do bazy danych przy użyciu ORM w celu wykonania określonego zadania, w którym wykonano zadanie wyraźnie wskazane w nazwie metody. Powód, dla którego instrukcja jest tak długa, ponieważ łączy się w wielu kolumnach, stosuje wiele obszarów i wybiera wiele różnych kolumn, aby utworzyć wymagany udokumentowany format wyjściowy.

Czy taki trudny do odczytania kod jest uważany za zły kod? Podobnie, jeśli piszę kod skomplikowanego algorytmu, w wyniku którego kod jest trudny do odczytania i jest zawinięty w jasno nazwaną metodę, czy kod ten jest zły?

readability Michael Tsang
źródło
Czy nie ma możliwości parametryzowania zapytania w jakikolwiek sposób? Zgaduję, że to zapytanie różni się w zależności od tego, co dzieje się w tworzonej metodzie. Być może możesz go rozbić na mniejsze części i zbudować w kilku krokach, aby ułatwić czytanie.
Zalomon
Czy Twoja ORM obsługuje widoki? Możesz wyodrębnić (grupę) złączenie w widoku, a następnie wybrać widok. Nawet jeśli widok nie jest używany gdzie indziej, może to pomóc w rozbiciu dużej instrukcji SQL
Caleth
Czy Twój ORM obsługuje język zapytań podobny do SQL? Jeśli tak, możesz przenieść zapytanie do własnego pliku i włączyć dla niego podświetlanie składni IDE. W aplikacji załaduj zapytanie z pliku. Jeśli twoje IDE nie obsługuje dokładnie tego konkretnego języka zapytań, możesz dogadać się z formatowaniem SQL, nawet jeśli nie jest to idealne. Jednak czytelność jest znacznie zwiększona przez dobre formatowanie. Ma to również tę zaletę, że łatwo skopiować zapytanie na scratchpad i tam dokonać modyfikacji.
SpaceTrucker

Odpowiedzi:

17

Napisałeś

Czy taki trudny do odczytania kod jest uważany za zły kod

więc zdecydowanie zgadzasz się, że jest to kod trudny do odczytania , a jeśli jest trudny do odczytania, jest trudny do utrzymania i ewolucji - więc myślę, że według własnego uznania uważasz kod za „zły”. Czasami jednak nie jest oczywiste, jak poprawić coś takiego jak 50-wierszowa instrukcja SQL. Łatwe refaktoryzacje metodą „wyodrębnij” nie działają i prawdopodobnie nie masz pojęcia, od czego zacząć od uczynienia kodu bardziej czytelnym. W takich przypadkach nadal możesz wypróbować jedną lub wszystkie z poniższych opcji

  • pokaż kod komuś, kto ma większe doświadczenie w czyszczeniu kodu niż Ty. Jeśli nie masz kogoś w swojej organizacji, możesz zapytać, spróbuj codereview.stackexchange

  • spróbuj wyszukać w Google konkretny problem. Na przykład dobrym pomysłem może być na przykład „czyszczenie długiej instrukcji SQL”. Zdziwisz się, ile artykułów znajdziesz na ten temat, a nawet jeśli nie możesz znaleźć przepisu na swoją sprawę, możesz uzyskać nowe pomysły

  • zamiast pytać o uzasadnienie rzeczy, których nie możesz zrobić, skoncentruj się na rzeczach, które możesz zrobić, aby oczyścić kod przynajmniej trochę, takich jak dodawanie odpowiednich podziałów wierszy, właściwe wcięcia, dodawanie komentarzy wyjaśniających, poprawianie niektórych zmiennych imię. Nie jest mało prawdopodobne, że podczas tego procesu, zmuszając się do ponownego przeczytania szczegółów kodu, znajdziesz sposób na przekształcenie kodu na mniejsze jednostki

  • ćwiczyć, ćwiczyć, ćwiczyć. „Czystego kodowania” nie uczy się w ciągu jednego dnia, staje się łatwiejsze z większym doświadczeniem. Być może dzisiaj nie znajdziesz rozwiązania swojego problemu, ale kiedy wrócisz do kodu za kilka miesięcy, będzie on wyglądał inaczej.

Doktor Brown
źródło
Nie zgadzam się z częścią komentarza, jeśli jest złożona część kodu, która jest złożona, ponieważ nie może być inaczej ORAZ nie znalazłem sposobu jej uproszczenia, komentarze raczej nie dają pełnego obrazu tego, co się dzieje. Udokumentuj to za pomocą jakiegoś schematu byłoby znacznie lepiej. I należy pozostawić komentarz dotyczący tej zewnętrznej dokumentacji. Oczywiście sytuacja ta musi być wyjątkowa, ponieważ wszyscy wiemy, że utrzymanie dokumentacji zewnętrznej jest rzadko wykonywane, więc im mniej, tym lepiej. Co do reszty, jak zawsze dobrą odpowiedź.
Walfrat
@Walfrat: moim zamiarem było przedstawienie ogólnych wytycznych dotyczących tego procesu, nie tylko dla „50 linii kodu SQL”, a nie jako „gotowe rozwiązanie” ze wszystkimi potencjalnymi podejściami.
Doc Brown,
Wiem, chciałem tylko zasugerować, że jeśli po wielokrotnym sprawdzeniu czegoś nie można go wystarczająco uprościć (cokolwiek to jest), komentarze prawdopodobnie nie pomogą w złożeniu sprawy, dlatego wymagana będzie minimalna dokumentacja zewnętrzna. W konkretnym przypadku zapytań do bazy danych jest to jeszcze łatwiejsze, pokazując diagram pokazujący, jak każda część zapytania koreluje ze sobą.
Walfrat
4

Trudny do odczytania nie jest zły - niepotrzebnie trudny do odczytania jest zły.

Niektóre rzeczy są po prostu trudne. W takim przypadku musisz całkowicie zrozumieć problem, napisać kod i skomentować go tak dobrze, jak to możliwe, aby następny programista miał szansę.

Ale niektóre rzeczy są trudne tylko dlatego, że je utrudniłeś. Jeśli problem można uprościć i uprościć, uprość go. Jeśli jest to trudne do zrozumienia, ale można je rozsądnie podzielić na podproblemy, podziel je na podproblemy, aby uprościć.

gnasher729
źródło
Dokładnie. Postaraj się, aby kod sam się dokumentował, a następnie użyj komentarzy, aby wypełnić luki. (edytowane: po opublikowaniu komentarza zdałem sobie sprawę, że OP odnosi się do zapytań do bazy danych ORM, a nie SQL).
Kyle A
1

ORM, aby utworzyć raport? Poważnie? Naucz się trochę SQL, stary. Języki proceduralne są straszne w tego rodzaju sprawach.

SQL jest językiem znacznie lepiej zaprojektowanym do obsługi skomplikowanych połączeń i selekcji. I nawet jeśli nie możesz sprawić, by SQL wyglądał pięknie, dostępne są wszelkiego rodzaju narzędzia do wizualizacji, w których możesz przeciągać i upuszczać obiekty bazy danych na diagramie, a SQL zostanie dla Ciebie wygenerowany. Nie wspominając o tym, że będziesz mógł dostroić i zoptymalizować zapytanie, przejrzeć jego plan zapytań, poprosić platformę o zasugerowanie dodatkowych opcji indeksowania itp. Jest to po prostu o wiele bardziej elastyczne.

Jestem pewien, że niektórzy ludzie tutaj się ze mną nie zgodzą, ale ORM nie nadaje się do skomplikowanych celów sprawozdawczych. Jeśli to w ogóle możliwe, rozważę odejście od tego i przejście na język zapytań strukturalnych .

John Wu
źródło
2
Szczerze mówiąc, fakt, że nie lubisz ORM, jest całkowicie nieistotny dla tego pytania.
Doc Brown,
Lubię ORM w porządku. Twierdzę, że nie są dobrym narzędziem, gdy kod „łączy się w wielu kolumnach, stosuje wiele obszarów i wybiera wiele różnych kolumn w celu uzyskania wymaganego udokumentowanego formatu wyjściowego”, co jest tematem tego wątku.
John Wu,
0

Ogólnie trudny do odczytania kod jest złym pomysłem w dowolnym miejscu - nawet jeśli jesteś jedynym opiekunem - miałem kilka razy wracałem do jakiegoś kodu lata lub nawet tygodnie później i nie mogłem się skupić.

Jeśli musisz dużo zrobić w jednym zapytaniu, spróbuj podzielić go na wiersze z osadzonymi komentarzami:

query(join(map(condition1, condition2), blah, blah, something(bah, blah, blah)))

Staje się:

// Why are we doing such an awful single query rather than a sequence of selects?
query( // Description of query
  join( // Why are you doing a join here
    map( // Why a map
      condition1, // What is this
      condition2  // And this
   ), // End Map
   blah, // What, Why?
   blah, // What, Why?
   something( // What does this do?
      bah, // What, Why?
      blah, // What, Why?
      blah // What, Why?
      ) // End Something
   ) // End Join
) // End Query
Steve Barnes
źródło
Jestem niejednoznaczny co do twojego przykładu. komentarze powinny wyjaśniać, dlaczego kod jest taki, jaki jest. Co powinno być wyrażane za pomocą identyfikatorów ...
Timothy truckle
@TimothyTruckle Zgadzam się, że identyfikatory powinny jasno określać, jakie są, ale często są niejasne w normalnym kodzie - w przypadku nazw pól rekordów często brakuje jasności z powodu ograniczeń historycznych, z którymi się spotkałem, przypadki, w których nazwy pól były ograniczone do 5 znaków, z których wszystkie musiały być dużymi literami ASCII i nie mogły zostać zmienione ze względu na wymagania kompatybilności, np. z ulubionym narzędziem raportowania MD.
Steve Barnes,
0

Oprócz doskonałej odpowiedzi @ DocBrown, myślę, że warto zauważyć, że nikt nie pisze przez cały czas „dobrego” kodu. Kodowanie powoduje kompromisy i często lepiej jest zaakceptować fakt, że napisałeś coś nieco mniej czystego, niż chcesz, i powrócić do tego później. Refaktoryzacja to proces ulepszania kodu w miarę upływu czasu - i z mojego doświadczenia wynika, że ​​to stanowi dobrą bazę kodu, a nie „poprawienie go za pierwszym razem”.

I oceniasz kod na poziomie aplikacji, a nie na poziomie poszczególnych metod / linii kodu. Więc jeśli masz złożoną metodę, ale jest ona wyraźnie nazwana, nie sądzę, że masz „zły” kod, o ile metoda jest spójna.

Nazewnictwo jest największą bronią, którą posiadasz, aby kod był zrozumiały - nadaj swojej metodzie nazwę, która pozwala czytającym kod na pomijanie ciała, jeśli zajdzie taka potrzeba. Nazwij swoje zmienne itp. W taki sposób, aby czytelnicy mogli zobaczyć, co reprezentują, bez konieczności czytania instrukcji przypisania.

Następną rzeczą jest upewnienie się, że twoja metoda naprawdę robi tylko jedną rzecz - efekty uboczne sprawiają, że kod jest trudny do zrozumienia. Jeśli więc metoda zwraca dane dla formatu wyjściowego, nie powinna również aktualizować stanu bazy danych do „wydrukowanego” ani żadnego innego.

Warstwowanie / komponowanie to kolejna rzecz, którą możesz zrobić - jeśli masz kilka złożonych metod, które generują wyniki ORM, połącz je razem, aby czytelnicy twojego kodu mogli założyć, że wszystkie zachowują się w ten sam sposób, nie mają skutków ubocznych itp.

Neville Kuyt
źródło