Hiperłącza, zewnętrzna dokumentacja kodu źródłowego [zamknięte]

Dlaczego nadal umieszczamy opisy kodu źródłowego w języku naturalnym (tj. Powód, dla którego napisano wiersz kodu) w kodzie źródłowym, a nie jako osobny dokument?

Biorąc pod uwagę rozległą nieruchomość oferowaną nowoczesnym środowiskom programistycznym (monitory o wysokiej rozdzielczości, podwójne monitory itp.), IDE może zapewnić panele z pół-blokadą, w których kod źródłowy jest wizualnie oddzielony - ale nieodłącznie powiązany z - odpowiednie komentarze. Na przykład programiści mogą pisać komentarze do kodu źródłowego w hiperłączonym języku znaczników (łączącym się z dodatkowymi wymaganiami oprogramowania), co jednocześnie zapobiegałoby zaśmiecaniu kodu źródłowego przez dokumentację.

Jakie niedociągnięcia hamowałyby taki mechanizm tworzenia oprogramowania?

Makieta, która pomoże wyjaśnić pytanie:

Gdy kursor znajduje się w określonej linii w kodzie źródłowym (pokazanej na niebieskim tle powyżej), dokumentacja odpowiadająca linii pod kursorem jest podświetlona (tj. Odróżniona od innych szczegółów). Jak zauważono w pytaniu, dokumentacja pozostanie w fazie blokowania kodu źródłowego, gdy kursor przeskakuje przez kod źródłowy. Skrót klawiszowy może przełączać się między „trybem dokumentacji” a „trybem programowania”.

Potencjalne zalety to:

• Więcej kodu źródłowego i więcej dokumentacji na ekranach jednocześnie
• Możliwość edycji dokumentacji niezależnie od kodu źródłowego (niezależnie od języka?)
• Napisz dokumentację i kod źródłowy równolegle bez konfliktów scalania
• Dokumentacja hiperłącza w czasie rzeczywistym z doskonałym formatowaniem tekstu
• Tłumaczenie maszynowe quasi-w czasie rzeczywistym na różne języki naturalne
• Każda linia kodu może być wyraźnie powiązana z zadaniem, wymaganiami biznesowymi itp.
• Dokumentacja może automatycznie sygnalizować czasowo, kiedy każdy wiersz kodu został napisany (metryki)
• Dynamiczne włączanie diagramów architektury, obrazów w celu wyjaśnienia relacji itp.
• Dokumentacja z jednego źródła (np. Fragmenty kodu znacznika do włączenia instrukcji obsługi).

Uwaga:

• Okno dokumentacji można zwinąć
• Nie wpłynie to na przepływ pracy podczas przeglądania lub porównywania plików źródłowych
• Sposób realizacji jest szczegółem; dokumentacja może być:
  • przechowywane na końcu pliku źródłowego;
  • podzielone na dwa pliki według konwencji ( filename.c, filename.c.doc); lub
  • w pełni sterowany bazą danych
• Przez dokumentację z hiperłączem rozumiem odsyłacz do źródeł zewnętrznych (takich jak StackOverflow lub Wikipedia) i dokumentów wewnętrznych (tj. Wiki w subdomenie, która mogłaby odnosić się do dokumentacji wymagań biznesowych) i innych plików źródłowych (podobnych do JavaDocs).

Powiązany wątek: Co z awersją do dokumentacji w branży?

Ten problem ciągle mi przeszkadza i właśnie wpadłem na pomysł, w którym kierunku powinniśmy spróbować go rozwiązać (tak znalazłem to pytanie).

Myślę, że problem z dołączoną dokumentacją został źle uznany, gdy zdecydowaliśmy się dołączyć dokumentację użytkownika do kodu źródłowego. Tak jak docco.

Przede wszystkim pozwala odróżnić komentarze do kodu od dokumentacji użytkownika.

Komentarze do kodu zwykle są najlepsze, gdy są krótkie, w rzeczywistości super krótkie, więc mogę właściwie odczytać kod, który robi to bez konieczności zobaczenia poezji o tym, dlaczego i jak to działa.

Komentarze użytkowników są przeznaczone dla osób próbujących korzystać z biblioteki / interfejsu API i mogą zawierać przykłady użycia, wyjaśnienie, dlaczego została zaimplementowana w ten sposób, lub instrukcje dotyczące rozszerzenia biblioteki. Tego rodzaju komentarze bywają naprawdę pełne.

Zgadzam się z tym, że dokumentacja powinna być napisana zwykłym tekstem, więc nie jest ustalona przez sprzedawcę i łatwo ją dodać w VCS. Myślę jednak, że trzymanie dokumentacji użytkownika w pliku źródłowym było dużym błędem z co najmniej dwóch powodów:

• Trudniejszy do odczytania kod
• Niewystarczająco elastyczna dokumentacja (załóżmy, że potrzebuję dwóch stron dokumentacji wykorzystujących ten sam przykładowy kod lub posiadających jedną stronę dokumentacji wymagającą przeplatania kodu z dwóch różnych plików źródłowych).

Dlaczego więc chcemy mieć to w tym samym pliku? Cóż, nikt nie chce, aby ich dokumentacje nie były zsynchronizowane z kodem. Ale robimy to i tak, a zwłaszcza teraz dni z wielkim sukcesem Markdown. Wydaje mi się, że jest to właściwa ścieżka, ale jeśli się nie uda, to niech będzie.

Kiedy przeplatamy komentarz kodu z komentarzem użytkownika, mamy wiązanie dwukierunkowe. To pozwala nam łatwo zobaczyć, który komentarz odpowiada której części kodu. Możemy również sprawdzić, czy jakiś kod jest nieudokumentowany. To, czego nie oferuje, to sposób na sprawdzenie, czy komentarz jest aktualizowany, czy też nie, a dzieje się tak często, gdy kod jest trudny do odczytania (ponieważ dokumentacja czyni go brzydkim).

Co jeśli zamiast wiązania 2-kierunkowego mamy jeden sposób ?. Dokumentacja wskazująca na kod. Możemy mieć kod przeceny ze specjalnymi poleceniami, takimi jak:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Ma to tę zaletę, że znaczniki z niektórymi dodatkami, a przy użyciu odpowiednich narzędzi, moglibyśmy zwiększyć jego wartość.

Wyobraź sobie, że to jednokierunkowe wiązanie za pomocą narzędzi takich jak chrząknięcie (nawet przy zadaniu obserwacyjnym). Możesz wykryć, kiedy zmienia się plik źródłowy, zobaczyć, jakie pliki dokumentacji zależą od niego i ostrzec użytkownika (lub zaznaczyć go gdzieś), jeśli skomentowany kod ulegnie zmianie.

404 - Nie znaleziono strony

Podczas pracy z kodem nie chcesz, aby komentarze zginęły, i tak się stanie, gdy rozdzielisz kod i komentarze na osobne dokumenty.

Ponadto utrzymywanie wersji między dokumentem komentarza a dokumentem kodu spowoduje więcej bólu niż zysku.

Niektóre z twoich sugestii bardzo mi się podobają, ale można je łatwo wdrożyć, mając jednocześnie kod i komentarze w jednym pliku.

Możliwe wady, które widzę:

• Potrzebujesz specjalnego edytora, który implementuje tę funkcję

• Kod nie jest już tylko zwykłym tekstem, łatwy do manipulowania i zatwierdzania w VCS-es

• Do pracy z kodem potrzebna jest dwukrotnie większa szerokość ekranu

Co do twoich argumentów:

Więcej kodu źródłowego i więcej dokumentacji na ekranach jednocześnie

Ale może być niewygodny, jeśli chcesz przeglądać dwa pliki obok siebie.

Możliwość edycji dokumentacji niezależnie od kodu źródłowego (niezależnie od języka?)

Twierdziłbym, że w rzeczywistości jest to wada. Osobiście staram się, aby dokumentacja była jak najbliższa kodowi, aby nie stał się nieaktualny.

Napisz dokumentację i kod źródłowy równolegle bez konfliktów scalania

Ponownie, być może wada. Jeśli twoje dokumenty są głęboko powiązane z kodem, jak możesz je edytować niezależnie?

Dokumentacja hiperłącza w czasie rzeczywistym z doskonałym formatowaniem tekstu

Jeśli jest w kodzie, jest już w czasie rzeczywistym;) Jeśli chodzi o hiperłącza, przejście do definicji jest już zaimplementowane w większości IDE.

Tłumaczenie maszynowe quasi-w czasie rzeczywistym na różne języki naturalne

Nie rozumiem, dlaczego nie możesz tego robić za pomocą regularnych komentarzy / dokumentów.

Każda linia kodu może być wyraźnie powiązana z zadaniem, wymaganiami biznesowymi itp.

Nie jestem tego pewien ... Czy nie można tego osiągnąć za pomocą regularnych komentarzy?

Dokumentacja może automatycznie sygnalizować czasowo, kiedy każdy wiersz kodu został napisany (metryki)

Czy VCS-y nie zapewniają już tego rodzaju informacji?

Powiedziawszy to, podoba mi się sam układ - ale nie widzę potrzeby zmiany formatu pliku, wygenerowanie go z regularnych komentarzy nie jest takie trudne. Istnieje wiele generatorów dokumentacji, które to robią, np. Docco i jego następcy, tacy jak Pycco lub Marginalia .

Po pierwsze, komentarze doktora muszą iść w parze z kodem - przeniesienie ich w inne miejsce sprawia, że ​​obsługa rzeczy jest niezwykle trudna do osiągnięcia przy praktycznie zerowym wzmocnieniu. Więc po co zawracać sobie głowę!

Można jednak wziąć te osadzone komentarze i ukryć je w edytorze, pokazując je w dymku lub w podpowiedzi lub w razie potrzeby. Mam nadzieję, że takie podejście może zachęcić ludzi do napisania o wiele większej ilości dokumentacji do kodu - np. Opis klasy mógłby iść z klasą, a nie w zewnętrznym dokumencie projektowym.

Obecnie można osadzać hiperłącza w komentarzach do kodu, a także generować dokumenty z kodu za pomocą narzędzi takich jak Doxygen lub Sphinx. Wydaje mi się, że wystarczyłoby jakieś fantazyjne rozszerzenie edytora kodu, aby lepiej obsługiwać te narzędzia.

Nie podłączałbym żadnych wierszy kodu do narzędzia do śledzenia błędów ani narzędzia wymagań, to lepsze zadanie dla twojego SCM. Następnie możesz zobaczyć zmiany kodu dla każdego zatwierdzenia, które są powiązane z zadaniem. Nie zintegrowałbym również dokumentacji przechowywanej w kodzie z modułem do śledzenia błędów - byłbyś przykręcony, gdybyś kiedykolwiek chciał przeprowadzić migrację do nowej (hmm, widzę, że ta funkcja jest dodawana do TFS teraz) lub jeśli straciłem historię zmian (co się dzieje)

Oprócz tego, co @Bogdan już stwierdził, dodałbym kilka:

• Skonfigurowałem moje IDE, aby zawsze zawierało 2 pliki jednocześnie. Dzięki funkcji, którą sugerujesz, potrzebowałbym 2 monitorów, aby zobaczyć tę samą ilość informacji, i 3, aby zrobić to, co teraz robię z 2.
• Przeglądając plik, nie widzisz od razu komentarzy, a jeśli nie wiesz dokładnie, czego szukasz, bardzo trudno go znaleźć.
• Podczas przeszukiwania pliku nie mogę przeszukiwać komentarzy bezpośrednio (ani tak łatwo).
• Czasami muszę przeprowadzać różne testy / pisać krótkie fragmenty kodu na serwerze na żywo za pośrednictwem ssh . Chociaż funkcjonalność, o której mówisz, może być zintegrowana z VIM lub innymi edytorami wiersza poleceń - najprawdopodobniej wystąpiłyby dość duże problemy

• Większość IDE obsługuje zwijanie kodu / komentarzy , a końcowe wyniki są następujące:

  Zamiast normalnego:

  

Spraw, aby kod był bardziej czytelny na wypadek, gdybyś nie potrzebował komentarzy.

Kod źródłowy i dokumentacja, jak należy to zrobić.

http://jasmine.github.io/2.3/introduction.html