Zbyt wielu programistów uważa, że kod jest wszystkim, czego potrzebują. A potem nieuchronnie dochodzą do momentu, w którym stwierdzają, że nie rozumieją projektu.
O co chodzi z ARCHITECTURE.md?
Jeśli prowadzisz projekt open-source obejmujący, powiedzmy, 10 000 - 200 000 linii kodu, warto rozważyć dodanie do niego pliku ARCHITECTURE.md - obok standardowych README czy CONTRIBUTING. Zanim przejdziemy do szczegółów, zaznaczmy iż nie jest to kolejna rada w stylu „dokumentacja jest fajna, pisz jej więcej”.
Jaka jest największa różnica między okazjonalnym współautorem a głównym programistą w projekcie? Jest to znajomość fizycznej architektury projektu. Patrząc na problem w przybliżeniu: napisanie łatki zajmuje 2 razy więcej czasu, jeśli nie jesteś zaznajomiony z projektem. To i tak dużo ale przyznasz, że ustalenie, gdzie należy zmienić kod, zajmuje jeszcze jakieś 10 razy więcej czasu? Ta różnica może być trudna do zauważenia, jeśli pracujesz nad projektem przez jakiś czas. Jeśli z kolei jesteś nowy w projekcie to czytasz każdy plik jako sekwencję logicznych fragmentów określonych w jakiejś pseudolosowej kolejności. Jeśli wcześniej wniosłeś już jakiś wkład w kod, postrzeganie jest zupełnie inne. Masz w głowie coś na kształt mapy mentalnej kodu, więc nie czytasz go już po kolei. To nie tabula rasa. Zamiast tego po prostu skaczesz do miejsca, w którym powinna znajdować się poszukiwana przez Ciebie funkcja.
Panaceum
Plik ARCHITECTURE.md jest niewymagającym dużego wysiłku sposobem na wypełnienie tej luki. Jak nazwa wskazuje, plik ten powinien opisywać wysokopoziomową architekturę projektu. Mówiąc krótko: każdy dołączający się do pracy współpracownik będzie musiał to przeczytać. Im ten plik będzie krótszy, tym mniejsze będzie prawdopodobieństwo, że zdezaktualizuje się on w przyszłości przez jakąś zmianę w projekcie. To główna praktyczna zasada dla ARCHITECTURE.md – opisuj tylko te rzeczy, które raczej nie będą się często zmieniać. Nawet nie próbuj synchronizować jego treści ze zmianami w kodzie a zamiast tego dokonuj przeglądu pliku zaledwie kilka razy w roku.
Piszemy plik ARCHITECTURE.md
Jak go stworzyć? Zacznij od spojrzenia na rozwiązywany problem z generalnej perspektywy (z lotu ptaka). Następnie określ mniej lub bardziej szczegółowy codemap. Opisz najbardziej podstawowe moduły i ich wzajemne powiązania. Codemap powinien odpowiedzieć na pytanie gdzie jest to, co robi X?. Powinien również pomóc zorientować się w tym co robi to, na co patrzę?. Unikaj wchodzenia w szczegóły dotyczące działania każdego modułu, umieść to w osobnych plikach dokumentacji. Codemap jest mapą wszechświata a nie atlasem map poszczególnych ciał niebieskich. Wykorzystaj to jako okazję do zastanowienia się nad strukturą projektu.
Sprawdź oferty pracy na TeamQuest
Nazwij ważne pliki, moduły i typy. Nie łącz ich bezpośrednio (linki stają się szybko nieaktualne w miarę postępów w projekcie). Zamiast tego zachęć czytelnika do korzystania z wyszukiwania aby znaleźć wspomniane kwestie według nazwy. Nie wymaga to pracochłonnej konserwacji pliku i pomoże odkryć powiązane, podobnie nazwane rzeczy. Wiele podobnych funkcji ma przecież zbliżone do siebie nazwy, różniące się nieznacznie (zazwyczaj końcówką).
Po zakończeniu tworzenia mapy dodaj osobną sekcję dotyczącą problemów przekrojowych, dotyczących na raz większej ilości fragmentów kodu.
Dobrym przykładem dokumentu ARCHITECTURE.md jest ten z rust-analyzer.
Zobacz też jak tworzyć dokumentację w sposób automatyczny.
