Jak ułatwić zrozumienie dużej bazy kodu

Załóżmy, że rozwijam stosunkowo duży projekt. Udokumentowałem już wszystkie moje klasy i funkcje w Doxygen, jednak wpadłem na pomysł, aby umieścić „uwagi programisty” na każdym pliku kodu źródłowego.

Ideą tego jest wyjaśnienie laikom, jak działa określona klasa (i nie tylko dlaczego, jak większość komentarzy). Innymi słowy, aby dać innym programistom inne spojrzenie na działanie klasy.

Na przykład:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

Czy byłby to dobry sposób na ułatwienie nowym programistom / współpracownikom zrozumienia, jak to działa? Czy oprócz utrzymywania spójnego stylu kodowania i „standardowej” organizacji katalogów istnieją jakieś „standardy” lub zalecenia dotyczące tych przypadków?

To jest niesamowite. Chciałbym, aby więcej programistów poświęciło temu czas i wysiłek. To:

• Stwierdza w prostym języku angielskim, co robi klasa (tj. To jej odpowiedzialność),
• Zapewnia przydatne dodatkowe informacje o kodzie bez powtarzania dosłownie tego, co kod już mówi,
• Przedstawia niektóre decyzje projektowe i powody ich podjęcia, oraz
• Podkreśla niektóre problemy, które mogą spotkać następną osobę czytającą Twój kod.

Niestety, wielu programistów wpada w obóz „jeśli kod jest napisany poprawnie, nie trzeba go dokumentować”. Nie prawda. Istnieje wiele domniemanych związków między klasami kodu, metodami, modułami i innymi artefaktami, które nie są oczywiste po samym czytaniu samego kodu.

Doświadczony programista może starannie zaprojektować projekt o przejrzystej, zrozumiałej architekturze, która jest oczywista bez dokumentacji. Ale ile takich programów rzeczywiście widziałeś?

Kluczem do pracy z dużą bazą kodu nie jest konieczność czytania całej bazy kodu, aby dokonać zmiany. Aby umożliwić programistom szybkie znalezienie poszukiwanego kodu, kod powinien być zorganizowany, a organizacja widoczna. Oznacza to, że każda jednostka logiczna w kodzie, od pliku wykonywalnego, biblioteki, przestrzeni nazw, aż po indywidualną klasę, powinna mieć wyraźnie widoczną odpowiedzialność. Dlatego nie tylko dokumentowałbym pliki źródłowe, ale także katalogi, w których się znajdują.

Notatki twojego programisty dają również podstawy do decyzji projektowych. Chociaż może to być cenna informacja, oddzieliłbym ją od deklaracji odpowiedzialności (aby umożliwić czytelnikowi wybór, czy chce on przeczytać o odpowiedzialności klasy lub jej uzasadnieniu projektowym) i przenieść ją tak blisko źródła, które opisuje jak to możliwe, aby zmaksymalizować prawdopodobieństwo aktualizacji dokumentacji, gdy kod jest (dokumentacja jest użyteczna tylko wtedy, gdy możemy ufać jej dokładności - nieaktualna dokumentacja może być gorsza niż żadna!).

To powiedziawszy, dokumentacja powinna pozostać SUCHA, tzn. Nie powtarzać informacji, które mogłyby zostać wyrażone w kodzie lub zostały już opisane gdzie indziej (wyrażenia takie jak „jak stwierdza dokumentacja” są znakiem ostrzegawczym). W szczególności przyszli opiekunowie będą biegli w języku programowania projektu, tak jak w języku angielskim; sparafrazowanie implementacji w komentarzach (które widzę całkowicie zbyt często, gdy ludzie są dumni ze swojej dokumentacji) nie przynosi żadnych korzyści i prawdopodobnie odbiega od implementacji, w szczególności jeśli dokumentacja nie znajduje się w pobliżu opisanego kodu.

Wreszcie, struktura dokumentacji powinna zostać ujednolicona w całym projekcie, aby każdy mógł ją znaleźć (to królewski bałagan dokumentów Piotra w narzędziu do śledzenia błędów, Sue na wiki, Alan w pliku readme i John w kodzie źródłowym ...) .

Nie zgodziłbym się, że jest to bardzo dobre podejście, głównie ze względu na

1. Kiedy refaktoryzujesz projekt, przenosisz metody, dokumentacja się psuje.

2. Jeśli dokumentacja nie zostanie odpowiednio zaktualizowana, spowoduje to więcej zamieszania niż pomoże w zrozumieniu kodu.

Jeśli masz testy jednostkowe dla każdej metody / testy integracyjne dla każdego modułu, byłaby to dokumentacja własna, łatwiejsza w utrzymaniu i łatwiejsza do zrozumienia niż komentarze do kodu.

Tak, posiadanie odpowiedniej struktury katalogów zdecydowanie pomoże.

Osobiście jestem fanem dokumentu projektowego wysokiego poziomu - najlepiej napisanego PRZED jakimkolwiek kodem - który zawiera przegląd projektu oraz listę klas i zasobów. Odgórna konstrukcja znacznie upraszcza rzeczy - może to być „silnik gry -> sprzęt -> kontrolery -> joystick”; dlatego nowy programista powiedział, że „napraw” przycisk „a” na kontrolerze „xyz” będzie przynajmniej wiedział, od czego zacząć.

Zbyt wiele współczesnych języków ma tendencję do dzielenia kodu na setki małych plików, więc znalezienie odpowiedniego pliku może być wyzwaniem nawet dla umiarkowanego projektu.

Jeśli podstawa kodu jest duża - staram się dostarczyć dokument projektowy, który odwzorowuje kluczowe elementy jego projektu i implementacji . Nie chodzi tu o wyszczególnienie żadnej z używanych klas, ale o dostarczenie klucza do kodu i myśli, która pojawiła się w projekcie. Daje nadrzędny kontekst systemowi, jego komponentom i ich zastosowaniu.

Dokumenty projektowe powinny zawierać następujące elementy;

• Architektura aplikacji
• Logiczna struktura kodu
• Przepływy danych
• Zastosowane kluczowe wzorce i motywacja ich użycia
• Struktura źródła kodu
• Jak go zbudować (daje to wgląd w ukryte zależności i strukturę źródła kodu fizycznego)

Następnie dokumentacja klas oraz funkcje / metody powinny zostać odpowiednio uzupełnione . W szczególności publiczny interfejs API; powinno być jasne, co następuje w każdym przypadku;

• Warunki wstępne
• Efekty
• Niezmienniki
• Warunki wyjątkowe (rzuty)

Najważniejszą zasadą, którą znalazłem, aby ułatwić nowym programistom zrozumienie bazy kodu, że idealna zgoda jest droga.

Jeśli nowi programiści muszą doskonale rozumieć system, nad którym pracują, zapobiega to wszelkim możliwościom uczenia się w miejscu pracy. Myślę, że notatki programisty są doskonałym początkiem, ale poszedłbym dalej. Spróbuj napisać kod, który, jeśli podejdzie się na nowo, pozwoliłby programistom dowiedzieć się, co robią w locie, zamiast wymagać od nich uczenia się przedtem. Małe rzeczy, takie jak twierdzenia o przypadkach, o których wiesz, że nigdy nie mogą wystąpić, wraz z komentarzami wyjaśniającymi, dlaczego twierdzenie jest ważne, idą daleko. Podobnie dzieje się z pisaniem kodu, który kończy się niepowodzeniem, a nie segregowaniem, jeśli zrobisz coś źle.

Widziałem duże klasy z dokumentacją i po przeczytaniu dokumentacji nie mam pojęcia, do czego ta klasa powinna być dobra i dlaczego ktokolwiek miałby z niej korzystać! Jednocześnie potrzebowałem pewnej funkcjonalności i byłem absolutnie pewien, że musi istnieć klasa, która by sobie z tym poradziła, i nie mogłem jej nigdzie znaleźć - ponieważ nie było dokumentacji, która prowadziłaby mnie od tego, czego potrzebowałem do klasy robić to.

Pierwszą rzeczą, której chciałbym w dokumentacji, było tylko kilka zdań na temat tego, co robi klasa i dlaczego chciałbym jej użyć. Komentarze w pierwotnym pytaniu pod tym względem mają się całkiem dobrze. Po przeczytaniu tych komentarzy, gdybym miał joystick, który nie działa dobrze, ponieważ nie mogę zinterpretować dostarczanych wartości, wiedziałbym, jaki kod sprawdzić.

Podobnie do tego, co powiedział @meriton, podziel kod na osobne komponenty. Co więcej, podziel bazę kodu na osobne pakiety (pliki JAR, klejnoty, jajka itp.), Aby jeszcze bardziej wyjaśnić, w jaki sposób składniki są rozdzielone. Jeśli występuje błąd, programista musi tylko znaleźć pakiet, w którym znajduje się błąd i (mam nadzieję) tylko tam go naprawić. Nie wspominając o tym, że łatwiej jest przeprowadzać testy jednostkowe, a Ty możesz skorzystać z zarządzania zależnościami.

Inne rozwiązanie: zmniejsz bazę kodów. Im mniej kodu, tym łatwiej go zrozumieć. Refaktoryzuj nieużywany lub zduplikowany kod. Użyj deklaratywnych technik programowania . To oczywiście wymaga wysiłku i często nie jest możliwe ani praktyczne. Ale to jest godny cel. Jak napisał Jeff Atwood: najlepszy kod w ogóle nie ma kodu

W przypadku złożonych systemów może być warto nie tylko dokumentować każdy plik, ale także ich interakcje i hierarchię, a także strukturę programu i dlaczego.

Na przykład silnik gry jest zwykle dość złożony i trudno jest zdecydować, co nazywa się po stu warstwach abstrakcji. Może warto utworzyć plik taki jak „Architecture.txt”, aby wyjaśnić, w jaki sposób i dlaczego kod ma taką strukturę, i dlaczego jest tam ta bezcelowa warstwa abstrakcji.

Może to częściowo wynikać z faktu, że pojedynczy programista ma trudności z napisaniem go, ponieważ każdy rozumie tylko swoją część projektu.

Czasami możesz uzyskać te informacje z notatek kierownika projektu, ale to wszystko, co dostaniesz, ponieważ rzadko zapisują swoje notatki w tym formacie.