Co powinieneś zostawić swoim następcom?

Załóżmy, że jesteś jedynym programistą, który opuszcza pracę. Jakiego rodzaju informacje / materiały poza samym kodem powinieneś stworzyć i zostawić do wymiany?

Oczywistą odpowiedzią jest na pewno „cokolwiek byś chciał w nowej pracy”, ale minęło trochę czasu, odkąd zacząłem nową pracę i zapominam, jakie były najważniejsze rzeczy, których wtedy potrzebowałem.

Myślę:

• konta / hasła
• lokalizacja sprzętu, kopie zapasowe, płyty CD z oprogramowaniem

Co jeszcze?

• Konta i hasła
• Informacje o serwerze
• Dobry kod
• Dokumentacja
  • Diagramy i wyjaśnienia baz danych są niesamowite
  • Lista osobliwości w kodzie
• Procedury
• Wyjaśnienie ręcznych procesów lub okazjonalnych, nieoczywistych prac
• Lista programów, z których korzystały lub które okazały się pomocne
• Informacje kontaktowe ;)

Mocna filiżanka kawy i przeprosiny.

To jest to, co chciałbym, żeby mi zostało.

• Dokumentacja. Jak trudno napisać kilka komentarzy? Twórz notatki, uwagi dotyczące wdrażania, przenoszenie uwag systemowych. Co zrobić, gdy uruchomisz ponownie i wszystko zniknie.
• Dokumenty tożsamości. Napisz, dlaczego tak się dzieje, więc nie muszę się zastanawiać, dlaczego nie robisz tego w inny sposób. Jak działa system tworzenia kopii zapasowych, jak serwer reaguje na obciążenia, testy, przypadki testowe, przypadki użycia.
• Notatki „Podczas korzystania z bazy danych nigdy nie mów SELECT * FROM clients. Nie jesteśmy pewni, dlaczego, ale zrzuca ona bazę danych” .

Mój adres e-mail, a może nawet numer telefonu.

Z mojego doświadczenia trudno jest zapisać każdy szczegół, więc najlepszą rzeczą jest być dostępnym (do pewnego stopnia), jeśli następcy będą potrzebować więcej informacji.

Dokumentacja napisanych programów, np. Ich przeznaczenie, lokalizacja plików źródłowych do przyszłego rozwoju, hasła itp.

Może to znajdować się w kodzie jako komentarz lub na zewnątrz.

Więcej niż tylko dokumentacja, chciałbym wiedzieć, dlaczego niektóre decyzje zostały podjęte w momencie ich podjęcia. Obecnie używamy SWIG przy projekcie, a jeden z innych programistów chciał wiedzieć, dlaczego nie użyliśmy Boost :: Python. Prosta odpowiedź brzmiała, że ​​klient nie pozwalał wówczas na użycie wzmocnienia. Teraz jest inna historia.

Takie rzeczy pomogą im nie tylko zrozumieć projekt, ale także jakie ograniczenia / ograniczenia / wyzwania pokonały twoje wdrożenie. Da im to punkt wyjścia do przyszłej konserwacji i rozszerzenia funkcji.

Jedną rzeczą, o której nikt inny nie wspomniał (chociaż mogłem to przeoczyć), jest udokumentowanie, jak skonfigurować środowisko programistyczne. Zdaję sobie sprawę, że przez większość czasu wystarczy zainstalować kilka rzeczy, uzyskać najnowsze, skompilować i gotowe. Czasami jednak jest coś więcej (SharePoint to jedna z sytuacji, które przychodzą na myśl) i dokumentowanie, jaki kondensator strumienia należy skonfigurować, w jaki sposób będzie bardzo pomocny dla biednej duszy podążającej za tobą.

Jeśli jest to program komputerowy, jak zbudować cały system od zera (może to być kilka osobnych programów), jak stworzyć pakiet do dystrybucji (jakie ma zależności, np. Wersje .NET) i jak wdrożyć go na serwery do pobrania, jeśli ma to zastosowanie, lub wypal go na płycie CD lub DVD.

Jeśli jest to program internetowy, FTP i (jeśli dotyczy) dostęp SSH do serwera oraz jakie narzędzia są używane do lokalnego tworzenia i testowania kodu.

Jeśli jest to system osadzony, wykonaj pełne instrukcje dotyczące budowania obrazu binarnego, jakich narzędzi używasz, jak pobrać i wgrać kod do produktu, jak skonfigurować system plików na urządzeniu, jeśli taki istnieje.

Niedawno zostawiłem ci pracę w podobnych okolicznościach (nie byłem jedynym programistą, ale tak naprawdę było nas tylko dwoje, więc miałem dość dużo wiedzy, której ten drugi facet nie miał (i odwrotnie, oczywiście)).

Jeśli chodzi o zwykłe dokumenty, ważne jest, aby udokumentować przegląd całego systemu. Poszczególne komponenty są już udokumentowane w kodzie, ale interakcja między komponentami i dlaczego tak się dzieje lub dlaczego to musi rozmawiać z tym komponentem jest ważna i nie zawsze jest łatwa do wykrycia poprzez debugowanie / przeglądanie kodu.

Następnie, przez około miesiąc przed moim odejściem, za każdym razem, gdy robiłem coś, co tylko mogłem zrobić, zapisywałem dokładnie, co się stało, co musiałem zrobić i dlaczego. Zazwyczaj był to przypadek „w komponencie xyz wystąpił błąd. Aby to naprawić, wiedziałem, że mogę przeglądać plik abc z powodu X, wtedy musiałem to zrobić, to i tamto”.

Oczywiście zostawiłem swój adres e-mail i numer telefonu na wypadek, gdyby pojawiło się coś, czego nie mogliby sami ustalić. Dostałem kilka telefonów w ciągu pierwszych kilku tygodni, ale one powoli odpadły.

Wszyscy chcielibyśmy uzyskać kompletny schemat przepływu danych systemu z listą wymagań funkcjonalnych. Bardziej niż prawdopodobne, że nigdy tego nie dostałeś, kiedy pisałeś system w pierwszej kolejności! Podobnie jak większość miejsc, najlepszą dokumentacją jest prawdopodobnie sam kod, więc to, co najbardziej bym chciał, to dobrze udokumentowany kod. Linie i linie komentarzy w kodzie wyjaśniające, co próbujesz zrobić zarówno technicznie, jak i funkcjonalnie.

Zasada nr 1 dla dokumentacji nie jest tym , co robi, ale dlaczego . Jaka jest historia uruchomionych programów i co robią?

Myślę, że chciałbym zobaczyć w dokumentacji oprócz tego, jakie funkcje zostały pominięte. Na przykład, dlaczego pewne idee NIE wdrożone lub pewna platforma lub metoda nie stosować (co było inaczej oczywistym wyborem).

Zapewnia to, że następca zawsze wie, czego nie robić, a jeśli jest bardziej zdolny, być może może wymyślić jakieś rozwiązanie i sprawić, by niektóre funkcje działały.

Dotyczy to szczególnie projektów typu open source. Może zaoszczędzić dużo czasu i mocy mózgu!