Jakie są dobre sposoby dokumentowania oprogramowania naukowego?

Wiele razy, kiedy odziedziczyłem lub napotkałem kod naukowy napisany przez innych ludzi (lub czasami nawet moją własną pracę), zauważyłem, że dokumentacja jest albo rzadka, albo nie istnieje. Jeśli mam szczęście, widzę pouczające komentarze. Jeśli mam szczęście, są nawet komentarze Doxygen i Doxyfile, więc mam interfejsy funkcyjne i trochę sformatowanego HTML do konsultacji. Jeśli mam szczęście, oprócz instrukcji Doxygen i komentarzy do plików źródłowych jest też instrukcja PDF i przykłady, i jestem zachwycony, ponieważ znacznie ułatwia mi życie.

Jakie informacje i narzędzia są przydatne w dokumentowaniu kodu źródłowego? W związku z tym, jakie informacje i narzędzia są przydatne do dokumentowania danych i wyników towarzyszących temu kodowi źródłowemu, w przypadku oprogramowania naukowego?

Myślę, że dokumentację oprogramowania naukowego można podzielić na trzy kategorie, z których wszystkie są niezbędne do pełnego zrozumienia. Najłatwiejszą i najczęstszą jest dokumentacja poszczególnych metod. Jest na to wiele systemów. Wspominasz doxygen , Python ma pydoc , aw PETSc mamy własny pakiet siewu, który generuje następujące .

Jednak w przypadku każdego oprogramowania, które wykracza poza proste narzędzie, potrzebujesz instrukcji. Zapewnia to ogólny widok celu pakietu oraz sposobu integracji jego różnych funkcji w celu osiągnięcia tego celu. Pomaga nowemu użytkownikowi ustrukturyzować kod, często za pomocą przykładów. W PETSc po prostu używamy LaTeX-a do instrukcji, ale pakiet PyClaw używa frameworka Sphinx , na którym jestem pod wielkim wrażeniem. Jedną z rzeczy, które zaimplementowaliśmy w pakiecie siewu, które uważam za bardzo przydatne, jest łącze między przykładowym kodem a dokumentacją funkcji. Na przykład ten przykładrozwiązuje równanie Bratu. Zwróć uwagę, jak możesz podążać za linkami dowolnego niestandardowego typu lub wywołania funkcji i przejść do dokumentacji niskiego poziomu oraz w jaki sposób strony te odwołują się do przykładów, które je wykorzystują. W ten sposób dowiaduję się o nowej funkcjonalności, którą wnoszą inne osoby w projekcie.

Myślę, że często pomijaną częścią dokumentacji jest dokumentacja programisty. Nierzadko publikuje się dokument w stylu kodowania oraz instrukcje dotyczące interakcji z repozytorium. Jednak bardzo rzadko wyjaśnia się decyzje projektowe podjęte przed wdrożeniem. Decyzje te zawsze wiążą się z kompromisami, a sytuacja w odniesieniu do sprzętu i algorytmów z czasem ulegnie zmianie. Bez dyskusji na temat omówionych kompromisów i uzasadnienia dla poszczególnych decyzji projektowych, późniejsi programiści mogą samodzielnie odtworzyć cały proces. Myślę, że jest to główna przeszkoda w udanej konserwacji i ulepszaniu starych kodów, gdy pierwotni programiści nie są już odpowiedzialni.

Dokumentacja w kodzie

Najważniejszą rzeczą jest użycie narzędzi dokumentacji w wybranym środowisku programistycznym, co oznacza pydoc dla python, javadoc w java lub komentarze xml w języku C #. Ułatwiają one pisanie dokumentacji w tym samym czasie, co pisanie kodu.

Jeśli polegasz na powrocie i dokumentowaniu rzeczy później, możesz nie poradzić sobie z tym, ale jeśli zrobisz to podczas pisania kodu, to, co należy udokumentować, będzie świeże w twoich myślach. C # ma nawet opcję wydania ostrzeżenia o kompilacji, jeśli dokumentacja XML jest niekompletna lub niezgodna z rzeczywistym kodem.

Testy jako dokumentacja

Innym ważnym aspektem jest dobra integracja i testy jednostkowe.

Często dokumentacja koncentruje się na tym, co klasy i metody robią w oderwaniu, pomijając ich wspólne użycie w celu rozwiązania problemu. Testy często umieszczają je w kontekście, pokazując, jak współdziałają ze sobą.

Podobnie testy jednostkowe często wyraźnie wskazują na zależności zewnętrzne, za pomocą których należy wykpić elementy .

Uważam również, że korzystając z programowania opartego na testach piszę oprogramowanie, które jest łatwiejsze w użyciu, ponieważ używam go od samego początku. Przy dobrej strukturze testowania ułatwienie testowania kodu i ułatwienie korzystania z niego to często to samo.

Dokumentacja na wyższym poziomie

Wreszcie jest co zrobić z poziomem systemu i dokumentacją architektoniczną. Wielu opowiada się za pisaniem takiej dokumentacji na wiki lub za pomocą Worda lub innego edytora tekstu, ale dla mnie najlepszym miejscem na taką dokumentację jest kod, w formacie zwykłego tekstu, który jest przyjazny dla systemu kontroli wersji.

Podobnie jak w przypadku dokumentacji w kodzie, jeśli przechowujesz dokumentację wyższego poziomu w repozytorium kodu, istnieje większe prawdopodobieństwo, że będziesz ją aktualizować. Korzyścią jest również to, że po wyciągnięciu wersji XY kodu otrzymujesz również wersję XY dokumentacji. Ponadto, jeśli używasz przyjaznego formatu VCS, oznacza to, że łatwo jest rozgałęziać, różnicować i scalać dokumentację, podobnie jak kod.

Bardzo lubię reStructuredText (rst) , ponieważ łatwo jest tworzyć zarówno strony HTML, jak i dokumenty PDF za pomocą sfinksa , i jest o wiele bardziej przyjazny niż LaTeX , ale nadal może zawierać wyrażenia matematyczne LaTeX, gdy są potrzebne.

Sprzeciwiam się niemal każdej kwestii, o której mówi Faheem . Konkretnie:

1 / „Myślę, że nierealistyczne jest oczekiwanie, że programiści naukowi spędzą dużo czasu na dokumentowaniu swojego oprogramowania”. Jest to recepta na nieudany projekt, z którego wkrótce nikt nie będzie mógł skorzystać, kto nie ma dostępu do głównych programistów. Nie bez powodu duże naukowe biblioteki komputerowe (np. PETSc lub deal.II) dysponują obszerną dokumentacją obejmującą 1000 lub więcej stron. Nie możesz mieć licznej społeczności użytkowników, jeśli nie masz obszernej dokumentacji. Zgadzam się jednak, że przykładowe kody muszą być proste i koncentrować się na jednej koncepcji.

2 / „w razie potrzeby autorzy powinni rozważyć napisanie artykułu do publikacji”. W praktyce często nie jest to możliwe. Można pisać artykuły na temat pojęć i algorytmów, ale nie na temat interfejsu i innych decyzji projektowych. Czytelnicy takich artykułów dowiedzą się, na czym polega wdrożenie; użytkownicy implementacji będą musieli wiedzieć, jakie funkcje wywołać, co oznaczają argumenty itp. Jako użytkownik można przez większość czasu żyć bez tego pierwszego i po prostu uznać bibliotekę za czarną skrzynkę, ale nie można się bez niej obejść informacje o interfejsie.

To dobre pytanie. W pierwszym przybliżeniu kod powinien próbować samodokumentować. Tak więc, na przykład, jeżeli oprogramowanie jest wiersz polecenia, należy być w stanie zrobić executable --helpani executable -hnawet executable(jeśli plik wykonywalny nie robi nic bez argumentów) i mają użytkowaniu krótki komunikat zwrotny.

Po drugie, uważam, że nierealistyczne jest oczekiwanie, że programiści naukowi spędzą dużo czasu na dokumentowaniu swojego oprogramowania, więc sugeruję, aby było to proste. Krótki tekstowy podręcznik z podstawowymi metodami i opcjami oraz z adnotacjami, działający i przetestowanyprzykłady użycia, stopniowane od prostych do bardziej złożonych (przykłady użycia są bardzo ważne i często zaniedbywane), są znacznie lepsze niż nic i znacznie więcej niż większość ofert oprogramowania naukowego. Chciałbym również dodać wkurza się na temat przykładów użycia. Proste oznacza proste. Oznacza to, że jeśli próbujesz zilustrować metodę, nie dodajesz dziesięciu obcych pojęć lub metod, które mylą czytelnika. Uprość i dodawaj adnotacje, aby czytelnik wiedział, co powinien robić przykład. Sugeruję również powiązanie przykładów użycia ręcznego z pakietem testowym, aby działały one po zmianie kodu. Właściwie to nie wiem, jak to zrobić w przyjemny sposób, więc proszę mnie uczyć. Jeśli programiści chcą uzyskać więcej fantazji, na pewno mogą używać ładnych języków znaczników i tak dalej, dodawać strony podręcznika itd.

Po trzecie, w razie potrzeby autorzy powinni rozważyć napisanie artykułu do publikacji. Zwykle odnosi się to do decyzji projektowych i daje perspektywę oprogramowania na wyższym poziomie niż robi to instrukcja, lub można się tego spodziewać. Dotyczyłoby to dokumentacji decyzji projektowych, o których mówił @Matt.

Oczywiście najważniejszą dokumentacją jest sam kod, który w razie potrzeby należy skomentować. Zakłada się, że kod jest wolnym oprogramowaniem. Jeśli tak nie jest, to jest znacznie mniej przydatne jako oprogramowanie naukowe (czy naprawdę chcesz użyć czarnej skrzynki, w której nie widzisz, w jaki sposób metody są wdrażane?), A ja dla jednej nie chciałbym jej użyć.

Aby odpowiedzieć na twoje pytanie, jak dokumentować dane i wyniki, polecam coś w rodzaju modułu doctest Pythona . Umożliwia to pisanie samouczków lub testów w sposób, który może być automatycznie sprawdzany.

Jeśli interesuje Cię umiejętność programowania, zajrzyj na org-babel . Jest częścią trybu org w Emacsie, a zatem zapewnia szeroki wachlarz opcji eksportu (LaTeX, PDF, HTML, ODT) do dokumentacji. Emacs może wyświetlać obrazy w buforze i umożliwia pisanie równań matematycznych w składni LaTeX, dzięki czemu nie musisz ograniczać się do dokumentacji tekstowej.

Dokumentacja, która jest automatycznie uzyskiwana z kodu źródłowego, jest niezbędnym składnikiem aktualności, tj. Poprawnej dokumentacji. Nie mogę policzyć, ile razy widziałem dokumentację, która jest wiele lat za kodem źródłowym z powodu apatii deweloperów do dokumentacji. Łatwym rozwiązaniem jest ułatwienie programistom pisania dokumentacji wraz z nowym kodem w tym samym miejscu w tym samym czasie, a nie jako wysiłek a posteriori, który nieuchronnie zostanie pozbawiony priorytetów na rzecz bardziej chwalebnych działań.

Gdybym był zmuszony dokonać wyboru, wolałbym mieć szczegółowe i dokładne (tj. Bieżące) komentarze do kodu źródłowego, ale nie mam instrukcji użytkownika niż nieaktualnej instrukcji użytkownika, która jest pełna błędnych informacji.

W Pythonie znajdują się narzędzia pep8 i pep257, które zgłaszają brakującą lub źle sformułowaną dokumentację. elpy dla Emacsa będzie również narzekać na brakującą dokumentację. Warto stosować się do konwencji docpy z Numpy z reStructuredText. Testy z pep8, pep257 i doctest można skonfigurować z py.test i toksykami uruchamianymi automatycznie.