Adnotuj kod źródłowy za pomocą diagramów jako komentarzy

14

Piszę dużo kodu (głównie c ++ i javascript), który dotyczy geometrii obliczeniowej i grafiki oraz tego rodzaju tematów, więc odkryłem, że diagramy wizualne są nieodzowną częścią procesu rozwiązywania problemów.

Właśnie ustaliłem, że „och, czy nie byłoby po prostu fantastycznie, gdybym mógł jakoś dołączyć ręcznie rysowany diagram do fragmentu kodu jako komentarz”, a to pozwoliłoby mi wrócić do czegoś, nad czym pracowałem, dni, tygodnie, miesiące wcześniej i znacznie szybciej odtwarzają moje algorytmy.

Jako wizualny uczeń uważam, że może to poprawić moją produktywność z prawie każdym rodzajem programowania, ponieważ proste diagramy mogą pomóc w zrozumieniu i uzasadnieniu każdego rodzaju nietrywialnej struktury danych. Na przykład wykresy. Podczas zajęć z teorii grafów na uniwersytecie byłem w stanie naprawdę dobrze zrozumieć relacje wykresów, z których w rzeczywistości mogłem narysować schematyczne przedstawienia.

Więc...

Według mojej wiedzy, żadne IDE nie pozwala na zapisanie zdjęcia jako komentarza do kodu.

Myślałem, że ja lub ktoś inny może wymyślić jakieś dość łatwe w użyciu narzędzie, które może przekonwertować obraz na ciąg binarny base64, który następnie mogę wstawić do mojego kodu.

Jeśli proces konwersji / wstawiania może być wystarczająco usprawniony, umożliwiłoby to znacznie lepsze połączenie między diagramem a rzeczywistym kodem, więc nie muszę już chronograficznie przeszukiwać moich notatników. Jeszcze bardziej niesamowite: wtyczki dla IDE do automatycznego analizowania i wyświetlania obrazu. Z teoretycznego punktu widzenia nie ma w tym absolutnie nic trudnego.

Domyślam się, że zajęłoby mi to trochę więcej czasu, aby dowiedzieć się, jak rozszerzyć moje ulubione IDE i utrzymać te wtyczki, więc byłbym całkowicie zadowolony z rodzaju postprocesora kodu, który wykonałby to samo parsowanie i renderowanie obrazów i pokazywanie ich obok kodu, w przeglądarce lub coś takiego. Ponieważ z zawodu jestem programistą javascript.

Co ludzie myślą? Czy ktoś za to zapłaci? Ja bym. Być może jednak chciałbym również zauważyć, że niezależnie od tego, czy ja lub jakaś znacząca liczba moich rówieśników zapłaciłaby za coś takiego, jedynym sposobem na osiągnięcie sukcesu może być wydanie open source.

Steven Lu
źródło
4
Alternatywa: komentarz w linku do lokalnego pliku obrazu, który otwiera się w domyślnej przeglądarce zdjęć.
Hand-E-Food,
Moją największą obawą byłoby nadużycie systemu. Pewnie, że zaczyna się od diagramu mającego znaczenie dla złożonego algorytmu, ale jak długo trzeba czekać, aż ktoś załaduje wątłe dokumenty specyfikacji do komentarzy dla klasy? Zanim się zorientujesz, wszystko, co dotyczy projektu + programisty, jest umieszczane w komentarzach do kodu. Oczywiście każdy potężny system jest podatny na nadużycia. Myślę, że potrzeba jest niszą, ale jeśli jesteś w tej niszy, byłoby to bardzo przydatne narzędzie.
Snixtor,
@ Hand-E-Food Nice! Adres URL pliku w komentarzu pojawia się jako klikalny link w Xcode po wyjęciu z pudełka. Moim jedynym zarzutem jest to, że utworzenie adresu URL pliku ścieżki względnej wydaje się niemożliwe, więc aspekt klikalnego łącza psuje się (najprawdopodobniej) podczas przełączania systemów.
Steven Lu,
Mogą Cię zainteresować
niebezpośrednie
Robię javadoc, który wygeneruje HMTL z obrazami. Lub SimpleDocBook, osobna dokumentacja, oparta na XML, do którego można / należy odwoływać się w kodzie reguł biznesowych. To zapewnia niezłą prozę i obejmuje system z perspektywy całej logiki biznesowej, zamiast rozproszenia komponentów oprogramowania i warstw (klas). Każde żądanie zmiany dodaje kod z odniesieniem do dokumentu docbook + wersja / numer biletu, a dokument docbook zawiera listę zmian + numer biletu. Działa to z powodu pełnego zasięgu. Nie jestem pewien, jak by to pasowało do Twojej sytuacji.
Joop Eggen

Odpowiedzi:

6

Co z wtyczką wstawiania obrazu dla programu Visual Studio ?

Jeśli używasz innego IDE i albo nie obsługuje on osadzonych obrazów, albo nie masz czasu na jego rozszerzenie, to co z umieszczeniem linku do obrazu w komentarzach, podczas gdy obraz będzie znajdować się gdzieś w repozytorium ?

Arseni Mourzenko
źródło
To fajnie. Używam VS w pracy, więc mogę to wypróbować! Dzięki. Zapisanie obrazu w repozytorium i powiązanie go w jakiś sposób jest zdecydowanie jednym ze sposobów na osiągnięcie tego, ale jestem pewien, że nadal jest to dla mnie zbyt wiele pracy księgowej, aby móc go niezawodnie wdrożyć. Jestem dość leniwym programistą.
Steven Lu,
Zapisywanie zdjęć w repozytorium działałoby również z większością metod przeglądania repozytoriów (np. Interfejs sieciowy repozytorium VCS)
Steven Lu,
4

Jeśli nie jesteś artystą ASCII , możesz użyć doxygen jako narzędzia dokumentacji wraz z zintegrowaną z nim aplikacją dot / graphviz .

Umożliwia to pisanie tekstowego opisu wykresów i renderowanie ich w dokumentacji.

Na przykład ten opis:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

renderuje jako:

wprowadź opis zdjęcia tutaj

mouviciel
źródło
To jest fajne! Jakieś wsparcie dla narzędzi dla środowisk Java? W tym Mojo nie widzę niczego, co przypominałoby obsługę tego, na przykład: graphviz-maven-plugin.bryon.us/dot-mojo.html . Wszystkie pozostałe mają właśnie obsługę plików .dot.
oligofren,
2

Możesz wypróbować tryb artysty emacsa. Robiłby sztukę ascii zamiast obrazów jako takich, więc może, ale nie musi być tym, czego szukasz. W szczególności, jeśli twoje IDE nie robi czcionek o stałej szerokości, nie byłoby to przydatne. Będąc zwykłym tekstem, grałaby bardzo ładnie z kontrolą wersji.

Oto zrzut ekranu z trybu artysty, dzięki czemu możesz dowiedzieć się, czy jesteś zainteresowany, czy nie.

Aby uruchomić tryb artysty w emacsie, wykonaj Alt-x, wpisz tryb artysty i naciśnij klawisz Return. Środkowy przycisk myszy wyświetla menu. Skróty klawiszowe do wycinania i wklejania nie są domyślnie normalnymi oknami, ale możesz włączyć tryb CUA, aby to zmienić.

Michael Shaw
źródło
Wow, to ... imponujące. W moim kodzie mam kilka komentarzy w stylu diagramu ASCII. To po prostu zbyt czasochłonne. Będę chciał użyć lepszych narzędzi, ponieważ technologia już tu jest. Czasami pisałem kod w Vimie, ale jakich skryptów służących do rozpoznawania kodu zabrakło mi w porównaniu z prawdziwymi IDE. Ale dzięki za pokazanie mi tej starej szkoły techniki!
Steven Lu,
Odwiedziłem kilka lat później i od tego czasu zebrałem kilka gadżetów Vima, aby pomóc w szybkim tworzeniu schematów pudełkowych. bez względu na to, czy są to znaki ascii, czy Unicode, jest to bardzo fajny sposób na upiększenie kodu fajnymi i przydatnymi komentarzami. Vim nie wychodzi jednak z pudełka po wyjęciu z pudełka.
Steven Lu
1

Co ludzie myślą? Czy ktoś za to zapłaci? Ja bym.

ZOMG, pasuję do podobnej kategorii jak ty i chciałbym taką funkcję bezpośrednio w IDE.

Na razie robię tak dużo „sztuki” ASCII jak to:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

Główną wartością, którą znajduję, jest widzenie nazw zmiennych odpowiadających diagramowi wizualnemu, szczególnie gdy używamy złożonych przejść siatek i takich dla nowych algorytmów siatki. Ta sztuczka generowania wykresów doksygenowych pokazana w jednej z odpowiedzi jest super fajna - powinienem spróbować jeszcze więcej.

Jest tak wiele rzeczy, które są łatwiejsze do komunikowania się również wizualnie, niekoniecznie nawet przy użyciu grafów. Przykład:

wprowadź opis zdjęcia tutaj

... lub to (porównanie mojego algorytmu nazywam „podpisem hakowym” do standardowego podziału CC używanego przez Pixar):

wprowadź opis zdjęcia tutaj

Dałoby to kodowi tak dużo kontekstu, aby zobaczyć, co robią te operacje i jak różnią się one w kodzie, ponieważ niektóre rzeczy najlepiej pokazać wizualnie. Zdjęcia naprawdę potrafią uchwycić tysiąc słów.

Byłoby więc dla mnie całkowicie senne mieć IDE, które pozwala mi widzieć kod i obrazy obok siebie, co pozwala mi osadzać obrazy w kodzie źródłowym.

Zwłaszcza, gdy wymyślamy nowe algorytmy, trudno jest znaleźć dobry sposób, aby opisać je bardzo dokładnie (z technicznego punktu widzenia, a nie dokładnie z perspektywy użytkownika) bez wchodzenia w etapy algorytmiczne, ponieważ nie ma nic, z czym można by je bezpośrednio porównać. Tego rodzaju obrazy przed i po zwykle pokazują od razu, czego można oczekiwać od algorytmu.

Kolejną rzeczą, o której marzę, jest wizualny debugger, który pozwala mi go zaprogramować, dzięki czemu niektóre moje typy danych mogą wyświetlać obraz w debuggerze, np. Aby zobaczyć wyniki wizualnie, gdy przeglądam kod i sprawdzam algorytmy Próbuję wymyślić, działają poprawnie na każdym kroku i pasują do tego, jak narysowałem to na papierze. Na przykład spraw, aby moja struktura danych siatki wyświetlała renderowany obraz w oknie obserwacyjnym debugera - idealnie, gdybym mogła nawet obrócić widok i tak tam i teraz.

Również podczas pracy w bardzo dużych bazach kodu (dziesiątki milionów LOC) napisanych przez luźne zespoły z tysiącem wtyczek, czasem może być koszmar po prostu dowiedzieć się, jak wykonać kod, który jest dla nas niejasny, rzadko używana wtyczka z interfejsu użytkownika. Byłoby tak niesamowicie w tych przypadkach, gdyby kod mógł osadzić miniaturowy zrzut ekranu pokazujący, jak faktycznie wywołać ten kod z interfejsu użytkownika (może być podatny na od czasu do czasu nieaktualne, ale zwykle interfejsy użytkownika nie są tak niestabilne w poprzek wersje, aby poprzednie ekrany były bezużyteczne).

Czy ktoś za to zapłaci? Ja bym.

W każdym razie tak, całkowicie! Chcę tego!!!


źródło
1
Niesamowite zdjęcia i podziękowania za napisanie (mimo że prawdopodobnie jest to raczej komentarz niż odpowiedź)! Niedawno postanowiłem całkowicie odpocząć od fajnej grafiki i symulacji i zbudować narzędzia do debugowania i śledzenia nowej generacji . To, o czym marzysz, jest bardzo podobne do rzeczy, o których marzę ...
Steven Lu
1
@StevenLu Często marzyłem o stworzeniu tego rodzaju IDE, które proponujesz za pomocą wizualnego debuggera (chociaż myślałem o zrobieniu tego od podstaw, ponieważ nie mogłem sobie wyobrazić rozwiązania wtyczki działającego tak dobrze po stronie debuggera). Ale tak - myślę, że ta odpowiedź była rodzajem komentarza ... ale byłam bardzo szczęśliwa widząc, że ktoś tego pragnie. W przeszłości moimi współpracownikami były bardziej techniczne i matematyczne - nie do końca rozumieli moje pragnienie komunikowania wszystkiego wizualnie.
1
Być może jednym z pseudonaukowych sposobów patrzenia na to jest to, że system wizualny jest daleko od siebie interfejsem o największej przepustowości, jaki mamy jako ludzie, i chociaż jest do bani, że mamy go tylko do użytku jako dane wejściowe, głęboka integracja systemu wizualnego z dostęp do pamięci mózgu umożliwia formatom wizualnym jednoznaczną przewagę w zakresie dokumentacji i rozpowszechniania abstrakcyjnych koncepcji. ... W tym celu pracuję nad narzędziem IDE-agnostycznym (zgodnie z filozofią Unix), które pozwala skompilowanym aplikacjom na automatyczne generowanie ustrukturyzowanych reprezentacji wizualnych jego elementów wewnętrznych, abyśmy mogli je zrozumieć.
Steven Lu
0

Brzmi jak przypadek użycia programowania literackiego, w którym można dodawać diagramy i cokolwiek do dokumentacji.

Przywróć Monikę - M. Schröder
źródło
Dlaczego głosowanie negatywne?
Przywróć Monikę - M. Schröder
Głosowałem za tobą. To bardzo dobra obserwacja, o której mówię prawie całkowicie mieści się pod tym parasolem.
Steven Lu
1
Głosowałem też za odrzuceniem, ponieważ tak naprawdę nie daje to odpowiedzi. Najwyraźniej nie chce przestawić całego programu na umiejętność programowania, a nawet jeśli tak, to programowanie to tylko podejście do programowania - niekoniecznie oznacza to, że obsługiwane są diagramy i obrazy.
Timmmm
0

Doxygen pozwala wstawiać obrazy w komentarzach takich jak to:

  /*! Here is a snapshot of my new application:
   *  \image html application.jpg
   */

Niestety wydaje się, że żadne IDE nie będą wyświetlać tych obrazów bezpośrednio, ale podejrzewam, że napisanie rozszerzenia VSCode nie byłoby zbyt trudne, aby to zrobić na przykład.

Znalazłem również jedno rozszerzenie VSCode, które już obsługuje to z innym komentarzem składniowym . Odbywa się to poprzez najechanie myszką:

VSCode dodaje funkcję, która pozwala na wstawianie obrazów - „wstawka kodu” - ale nie wydaje się jeszcze gotowa.

Oto zrzut ekranu z przykładowego rozszerzenia (którego nie udało mi się znaleźć - prawdopodobnie nie zostało jeszcze wydane, ponieważ wstawiony kod API nie został jeszcze wydany)

Timmmm
źródło